deepagents 1.9.0-alpha.1 → 1.9.1

package/dist/index.js

@@ -1,5 +1,4 @@
 import { AIMessage, HumanMessage, SystemMessage, ToolMessage, anthropicPromptCachingMiddleware, context, countTokensApproximately, createAgent, createMiddleware, humanInTheLoopMiddleware, todoListMiddleware, tool } from "langchain";
-import { ChatAnthropic } from "@langchain/anthropic";
 import { Command, REMOVE_ALL_MESSAGES, ReducedValue, StateSchema, getConfig, getCurrentTaskInput, getStore, isCommand } from "@langchain/langgraph";
 import { z } from "zod/v4";
 import micromatch from "micromatch";
@@ -247,7 +246,7 @@ function truncateIfTooLong(result) {
 * validatePath("C:\\Users\\file")  // Throws: Windows absolute paths not supported
 * ```
 */
-function validatePath(path) {
+function validatePath$1(path) {
 	const pathStr = path || "/";
 	if (!pathStr || pathStr.trim() === "") throw new Error("Path cannot be empty");
 	let normalized = pathStr.startsWith("/") ? pathStr : "/" + pathStr;
@@ -273,7 +272,7 @@ function validatePath(path) {
 function globSearchFiles(files, pattern, path = "/") {
 	let normalizedPath;
 	try {
-		normalizedPath = validatePath(path);
+		normalizedPath = validatePath$1(path);
 	} catch {
 		return "No files found";
 	}
@@ -305,7 +304,7 @@ function globSearchFiles(files, pattern, path = "/") {
 function grepMatchesFromFiles(files, pattern, path = null, glob = null) {
 	let normalizedPath;
 	try {
-		normalizedPath = validatePath(path);
+		normalizedPath = validatePath$1(path);
 	} catch {
 		return [];
 	}
@@ -540,6 +539,7 @@ async function resolveBackend(backend, runtime) {
 //#endregion
 //#region src/backends/state.ts
 const PREGEL_SEND_KEY = "__pregel_send";
+const PREGEL_READ_KEY = "__pregel_read";
 /**
 * Backend that stores files in agent state (ephemeral).
 *
@@ -577,12 +577,13 @@ var StateBackend = class {
 	* Get files from current state.
 	*
 	* In legacy mode, reads from the injected {@link BackendRuntime}.
-	* In zero-arg mode, reads from the LangGraph execution context via
-	* {@link getCurrentTaskInput}.
+	* In zero-arg mode, reads via {@link PREGEL_READ_KEY} with fresh=true,
+	* which applies any pending task writes through the reducer before returning.
 	*/
-	getFiles() {
-		if (this.runtime) return this.runtime.state.files || {};
-		return getCurrentTaskInput()?.files || {};
+	get files() {
+		if (this.runtime) return this.runtime.state.files ?? {};
+		const read = getConfig().configurable?.[PREGEL_READ_KEY];
+		return read?.("files", true) ?? {};
 	}
 	/**
 	* Push a files state update through LangGraph's internal send channel.
@@ -607,7 +608,7 @@ var StateBackend = class {
 	*          Directories have a trailing / in their path and is_dir=true.
 	*/
 	ls(path) {
-		const files = this.getFiles();
+		const files = this.files;
 		const infos = [];
 		const subdirs = /* @__PURE__ */ new Set();
 		const normalizedPath = path.endsWith("/") ? path : path + "/";
@@ -648,7 +649,7 @@ var StateBackend = class {
 	* @returns ReadResult with content on success or error on failure
 	*/
 	read(filePath, offset = 0, limit = 500) {
-		const fileData = this.getFiles()[filePath];
+		const fileData = this.files[filePath];
 		if (!fileData) return { error: `File '${filePath}' not found` };
 		const fileDataV2 = migrateToFileDataV2(fileData, filePath);
 		if (!isTextMimeType(fileDataV2.mimeType)) return {
@@ -668,7 +669,7 @@ var StateBackend = class {
 	* @returns ReadRawResult with raw file data on success or error on failure
 	*/
 	readRaw(filePath) {
-		const fileData = this.getFiles()[filePath];
+		const fileData = this.files[filePath];
 		if (!fileData) return { error: `File '${filePath}' not found` };
 		return { data: fileData };
 	}
@@ -677,7 +678,7 @@ var StateBackend = class {
 	* 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.` };
+		if (filePath in this.files) return { error: `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.` };
 		const mimeType = getMimeType(filePath);
 		const newFileData = createFileData(content, void 0, this.fileFormat, mimeType);
 		const update = { [filePath]: newFileData };
@@ -695,7 +696,7 @@ var StateBackend = class {
 	* Returns EditResult with filesUpdate and occurrences.
 	*/
 	edit(filePath, oldString, newString, replaceAll = false) {
-		const fileData = this.getFiles()[filePath];
+		const fileData = this.files[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 };
@@ -720,13 +721,14 @@ var StateBackend = class {
 	* Binary files are skipped.
 	*/
 	grep(pattern, path = "/", glob = null) {
-		return { matches: grepMatchesFromFiles(this.getFiles(), pattern, path, glob) };
+		const files = this.files;
+		return { matches: grepMatchesFromFiles(files, pattern, path, glob) };
 	}
 	/**
 	* Structured glob matching returning FileInfo objects.
 	*/
 	glob(pattern, path = "/") {
-		const files = this.getFiles();
+		const files = this.files;
 		const result = globSearchFiles(files, pattern, path);
 		if (result === "No files found") return { files: [] };
 		const paths = result.split("\n");
@@ -784,7 +786,7 @@ var StateBackend = class {
 	* @returns List of FileDownloadResponse objects, one per input path
 	*/
 	downloadFiles(paths) {
-		const files = this.getFiles();
+		const files = this.files;
 		const responses = [];
 		for (const path of paths) {
 			const fileData = files[path];
@@ -814,277 +816,633 @@ var StateBackend = class {
 	}
 };
 //#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
-*/
-const INT_FORMATTER = new Intl.NumberFormat("en-US");
-/**
-* Tools that should be excluded from the large result eviction logic.
-*
-* This array contains tools that should NOT have their results evicted to the filesystem
-* when they exceed token limits. Tools are excluded for different reasons:
-*
-* 1. Tools with built-in truncation (ls, glob, grep):
-*    These tools truncate their own output when it becomes too large. When these tools
-*    produce truncated output due to many matches, it typically indicates the query
-*    needs refinement rather than full result preservation. In such cases, the truncated
-*    matches are potentially more like noise and the LLM should be prompted to narrow
-*    its search criteria instead.
-*
-* 2. Tools with problematic truncation behavior (read_file):
-*    read_file is tricky to handle as the failure mode here is single long lines
-*    (e.g., imagine a jsonl file with very long payloads on each line). If we try to
-*    truncate the result of read_file, the agent may then attempt to re-read the
-*    truncated file using read_file again, which won't help.
-*
-* 3. Tools that never exceed limits (edit_file, write_file):
-*    These tools return minimal confirmation messages and are never expected to produce
-*    output large enough to exceed token limits, so checking them would be unnecessary.
-*/
-/**
-* All tool names registered by FilesystemMiddleware.
-* This is the single source of truth — used by createDeepAgent to detect
-* collisions with user-supplied tools at construction time.
-*/
-const FILESYSTEM_TOOL_NAMES = [
-	"ls",
-	"read_file",
-	"write_file",
-	"edit_file",
-	"glob",
-	"grep",
-	"execute"
-];
-const TOOLS_EXCLUDED_FROM_EVICTION = [
-	"ls",
-	"glob",
-	"grep",
-	"read_file",
-	"edit_file",
-	"write_file"
-];
-/**
-* Maximum size for binary (non-text) files read via read_file, in bytes.
-* Base64-encoded content is ~33% larger, so 10MB raw ≈ 13.3MB in context.
-* This keeps inline multimodal payloads within all major provider limits.
-*/
-const MAX_BINARY_READ_SIZE_BYTES = 10 * 1024 * 1024;
-/**
-* Template for truncation message in read_file.
-* {file_path} will be filled in at runtime.
-*/
-const READ_FILE_TRUNCATION_MSG = `
-
-[Output was truncated due to size limits. The file content is very large. Consider reformatting the file to make it easier to navigate. For example, if this is JSON, use execute(command='jq . {file_path}') to pretty-print it with line breaks. For other formats, you can use appropriate formatting tools to split long lines.]`;
-/**
-* Message template for evicted tool results.
-*/
-const TOO_LARGE_TOOL_MSG = context`
-  Tool result too large, the result of this tool call {tool_call_id} was saved in the filesystem at this path: {file_path}
-  You can read the result from the filesystem by using the read_file tool, but make sure to only read part of the result at a time.
-  You can do this by specifying an offset and limit in the read_file tool call.
-  For example, to read the first 100 lines, you can use the read_file tool with offset=0 and limit=100.
-
-  Here is a preview showing the head and tail of the result (lines of the form
-  ... [N lines truncated] ...
-  indicate omitted lines in the middle of the content):
-
-  {content_sample}
-`;
-/**
-* Message template for evicted HumanMessages.
-*/
-const TOO_LARGE_HUMAN_MSG = `Message content too large and was saved to the filesystem at: {file_path}
-
-You can read the full content using the read_file tool with pagination (offset and limit parameters).
-
-Here is a preview showing the head and tail of the content:
-
-{content_sample}`;
+//#region src/permissions/enforce.ts
 /**
-* Extract text content from a message.
-*
-* For string content, returns it directly. For array content (mixed block types
-* like text + image), joins all text blocks. Returns empty string if no text found.
+* Validate permission rule paths at setup time. Throws if any path is
+* relative, contains `..`, or contains `~`.
 */
-function extractTextFromMessage(message) {
-	if (typeof message.content === "string") return message.content;
-	if (Array.isArray(message.content)) return message.content.filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text).join("\n");
-	return String(message.content);
+function validatePermissionPaths(permissions) {
+	for (const permission of permissions) for (const path of permission.paths) validatePath(path);
 }
 /**
-* Build replacement content for an evicted HumanMessage, preserving non-text blocks.
-*
-* For plain string content, returns the replacement text directly. For list content
-* with mixed block types (e.g., text + image), replaces all text blocks with a single
-* text block containing the replacement text while keeping non-text blocks intact.
-*/
-function buildEvictedHumanContent(message, replacementText) {
-	if (typeof message.content === "string") return replacementText;
-	if (Array.isArray(message.content)) {
-		const mediaBlocks = message.content.filter((block) => typeof block === "object" && block !== null && block.type !== "text");
-		if (mediaBlocks.length === 0) return replacementText;
-		return [{
-			type: "text",
-			text: replacementText
-		}, ...mediaBlocks];
-	}
-	return replacementText;
+* Canonicalize and validate an absolute path before permission checking.
+*
+* Throws for:
+* - Empty or non-string input
+* - Non-absolute paths (must start with `/`)
+* - Paths containing `..`
+* - Paths containing `~`
+*/
+function validatePath(raw) {
+	if (typeof raw !== "string" || raw.length === 0) throw new Error("path must be a non-empty string");
+	if (!raw.startsWith("/")) throw new Error(`path must be absolute: ${JSON.stringify(raw)}`);
+	const segments = raw.split("/").filter((s) => s.length > 0);
+	if (segments.includes("..")) throw new Error(`path must not contain "..": ${JSON.stringify(raw)}`);
+	if (segments.includes("~")) throw new Error(`path must not contain "~": ${JSON.stringify(raw)}`);
+	return `/${segments.join("/")}`;
 }
 /**
-* Build a truncated HumanMessage for the model request.
+* Test whether `path` matches a glob `pattern`.
 *
-* Computes a preview from the full content still in state and returns a
-* lightweight replacement the model will see. Pure string computation — no
-* backend I/O.
-*/
-function buildTruncatedHumanMessage(message, filePath) {
-	const contentSample = createContentPreview(extractTextFromMessage(message));
-	return new HumanMessage({
-		content: buildEvictedHumanContent(message, TOO_LARGE_HUMAN_MSG.replace("{file_path}", filePath).replace("{content_sample}", contentSample)),
-		id: message.id,
-		additional_kwargs: { ...message.additional_kwargs },
-		response_metadata: { ...message.response_metadata }
-	});
-}
-/**
-* Create a preview of content showing head and tail with truncation marker.
+* Supports:
+* - `**` — any number of directory levels
+* - `*` — within a single path segment
+* - `{a,b}` — brace expansion
 *
-* @param contentStr - The full content string to preview.
-* @param headLines - Number of lines to show from the start (default: 5).
-* @param tailLines - Number of lines to show from the end (default: 5).
-* @returns Formatted preview string with line numbers.
+* Uses `micromatch` with `dot: true` so dotfiles are matched by default.
 */
-function createContentPreview(contentStr, headLines = 5, tailLines = 5) {
-	const lines = contentStr.split("\n");
-	if (lines.length <= headLines + tailLines) return formatContentWithLineNumbers(lines.map((line) => line.substring(0, 1e3)), 1);
-	const head = lines.slice(0, headLines).map((line) => line.substring(0, 1e3));
-	const tail = lines.slice(-tailLines).map((line) => line.substring(0, 1e3));
-	const headSample = formatContentWithLineNumbers(head, 1);
-	const truncationNotice = `\n... [${lines.length - headLines - tailLines} lines truncated] ...\n`;
-	const tailSample = formatContentWithLineNumbers(tail, lines.length - tailLines + 1);
-	return headSample + truncationNotice + tailSample;
+function globMatch(path, pattern) {
+	return micromatch.isMatch(path, pattern, { dot: true });
 }
 /**
-* Zod schema for legacy FileDataV1 (content as line array).
-*/
-const FileDataV1Schema = z.object({
-	content: z.array(z.string()),
-	created_at: z.string(),
-	modified_at: z.string()
-});
-/**
-* Zod schema for FileDataV2 (content as string for text or Uint8Array for binary).
-*/
-const FileDataV2Schema = z.object({
-	content: z.union([z.string(), z.instanceof(Uint8Array)]),
-	mimeType: z.string(),
-	created_at: z.string(),
-	modified_at: z.string()
-});
-/**
-* Zod v3 schema for FileData (re-export from backends)
-*/
-const FileDataSchema = z.union([FileDataV1Schema, FileDataV2Schema]);
-/**
-* Reducer for files state that merges file updates with support for deletions.
-* When a file value is null, the file is deleted from state.
-* When a file value is non-null, it is added or updated in state.
+* Evaluate permission rules against an operation + path and return the
+* access decision.
 *
-* This reducer enables concurrent updates from parallel subagents by properly
-* merging their file changes instead of requiring LastValue semantics.
+* First-match-wins; permissive default.
 *
-* @param current - The current files record (from state)
-* @param update - The new files record (from a subagent update), with null values for deletions
-* @returns Merged files record with deletions applied
+* @returns `"allow"` if the operation is permitted, `"deny"` otherwise.
 */
-function fileDataReducer(current, update) {
-	if (update === void 0) return current || {};
-	if (current === void 0) {
-		const result = {};
-		for (const [key, value] of Object.entries(update)) if (value !== null) result[key] = value;
-		return result;
+function decidePathAccess(rules, operation, path) {
+	for (const rule of rules) {
+		if (!rule.operations.includes(operation)) continue;
+		if (rule.paths.some((pattern) => globMatch(path, pattern))) return rule.mode ?? "allow";
 	}
-	const result = { ...current };
-	for (const [key, value] of Object.entries(update)) if (value === null) delete result[key];
-	else result[key] = value;
-	return result;
+	return "allow";
 }
+//#endregion
+//#region src/backends/composite.ts
 /**
-* 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.
+* Backend that routes file operations to different backends based on path prefix.
 *
-* Uses ReducedValue for files to allow concurrent updates from parallel subagents.
+* 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.
 */
-const FilesystemStateSchema = new StateSchema({ files: new ReducedValue(z.record(z.string(), FileDataSchema).default(() => ({})), {
-	inputSchema: z.record(z.string(), FileDataSchema.nullable()).optional(),
-	reducer: fileDataReducer
-}) });
-const FILESYSTEM_SYSTEM_PROMPT = context`
-  ## Following Conventions
-
-  - Read files before editing — understand existing content before making changes
-  - Mimic existing style, naming conventions, and patterns
-
-  ## Filesystem Tools \`ls\`, \`read_file\`, \`write_file\`, \`edit_file\`, \`glob\`, \`grep\`
-
-  You have access to a filesystem which you can interact with using these tools.
-  All file paths must start with a /.
-
-  - ls: list files in a directory (requires absolute path)
-  - read_file: read a file from the filesystem
-  - write_file: write to a file in the filesystem
-  - edit_file: edit a file in the filesystem
-  - glob: find files matching a pattern (e.g., "**/*.py")
-  - grep: search for text within files
-`;
-const LS_TOOL_DESCRIPTION = context`
-  Lists all files in a directory.
-
-  This is useful for exploring the filesystem and finding the right file to read or edit.
-  You should almost ALWAYS use this tool before using the read_file or edit_file tools.
-`;
-const READ_FILE_TOOL_DESCRIPTION = context`
-  Reads a file from the filesystem.
-
-  Assume this tool is able to read all files. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
-
-  Usage:
-  - By default, it reads up to 100 lines starting from the beginning of the file
-  - **IMPORTANT for large files and codebase exploration**: Use pagination with offset and limit parameters to avoid context overflow
-    - First scan: read_file(path, limit=100) to see file structure
-    - Read more sections: read_file(path, offset=100, limit=200) for next 200 lines
-    - Only omit limit (read full file) when necessary for editing
-  - Specify offset and limit: read_file(path, offset=0, limit=100) reads first 100 lines
-  - Results are returned using cat -n format, with line numbers starting at 1
-- Lines longer than ${INT_FORMATTER.format(MAX_LINE_LENGTH)} characters will be split into multiple lines with continuation markers (e.g., 5.1, 5.2, etc.). When you specify a limit, these continuation lines count towards the limit.
-  - You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.
-  - If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
-  - You should ALWAYS make sure a file has been read before editing it.
-`;
-const WRITE_FILE_TOOL_DESCRIPTION = context`
-  Writes to a new file in the filesystem.
-
-  Usage:
-  - The write_file tool will create a new file.
-  - Prefer to edit existing files (with the edit_file tool) over creating new ones when possible.
-`;
-const EDIT_FILE_TOOL_DESCRIPTION = context`
-  Performs exact string replacements in files.
-
-  Usage:
-  - You must read the file before editing. This tool will error if you attempt an edit without reading the file first.
-  - When editing, preserve the exact indentation (tabs/spaces) from the read output. Never include line number prefixes in old_string or new_string.
-  - ALWAYS prefer editing existing files over creating new ones.
-  - Only use emojis if the user explicitly requests it.
-`;
+var CompositeBackend = class {
+	default;
+	routes;
+	sortedRoutes;
+	constructor(defaultBackend, routes) {
+		this.default = isSandboxProtocol(defaultBackend) ? adaptSandboxProtocol(defaultBackend) : adaptBackendProtocol(defaultBackend);
+		this.routes = Object.fromEntries(Object.entries(routes).map(([k, v]) => [k, isSandboxProtocol(v) ? adaptSandboxProtocol(v) : adaptBackendProtocol(v)]));
+		this.sortedRoutes = Object.entries(this.routes).sort((a, b) => b[0].length - a[0].length);
+	}
+	/** Delegates to default backend's id if it is a sandbox, otherwise empty string. */
+	get id() {
+		return isSandboxBackend(this.default) ? this.default.id : "";
+	}
+	/** Route prefixes registered on this backend (e.g. `["/workspace"]`). */
+	get routePrefixes() {
+		return Object.keys(this.routes);
+	}
+	/**
+	* Type guard — returns true if `backend` is a {@link CompositeBackend}.
+	*
+	* Uses duck-typing on `routePrefixes` so it works across module boundaries
+	* where `instanceof` may fail.
+	*/
+	static isInstance(backend) {
+		return typeof backend === "object" && backend !== null && Array.isArray(backend.routePrefixes);
+	}
+	/**
+	* 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 LsResult with list of FileInfo objects (with route prefixes added) on success or error on failure.
+	*          Directories have a trailing / in their path and is_dir=true.
+	*/
+	async ls(path) {
+		for (const [routePrefix, backend] of this.sortedRoutes) if (path.startsWith(routePrefix.replace(/\/$/, ""))) {
+			const suffix = path.substring(routePrefix.length);
+			const searchPath = suffix ? "/" + suffix : "/";
+			const result = await backend.ls(searchPath);
+			if (result.error) return result;
+			const prefixed = [];
+			for (const fi of result.files || []) prefixed.push({
+				...fi,
+				path: routePrefix.slice(0, -1) + fi.path
+			});
+			return { files: prefixed };
+		}
+		if (path === "/") {
+			const results = [];
+			const defaultResult = await this.default.ls(path);
+			if (defaultResult.error) return defaultResult;
+			results.push(...defaultResult.files || []);
+			for (const [routePrefix] of this.sortedRoutes) results.push({
+				path: routePrefix,
+				is_dir: true,
+				size: 0,
+				modified_at: ""
+			});
+			results.sort((a, b) => a.path.localeCompare(b.path));
+			return { files: results };
+		}
+		return await this.default.ls(path);
+	}
+	/**
+	* 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 = 500) {
+		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 ReadRawResult with raw file data on success or error on failure
+	*/
+	async readRaw(filePath) {
+		const [backend, strippedKey] = this.getBackendAndKey(filePath);
+		return await backend.readRaw(strippedKey);
+	}
+	/**
+	* Structured search results or error string for invalid input.
+	*/
+	async grep(pattern, path = "/", glob = null) {
+		for (const [routePrefix, backend] of this.sortedRoutes) if (path.startsWith(routePrefix.replace(/\/$/, ""))) {
+			const searchPath = path.substring(routePrefix.length - 1);
+			const raw = await backend.grep(pattern, searchPath || "/", glob);
+			if (raw.error) return raw;
+			return { matches: (raw.matches || []).map((m) => ({
+				...m,
+				path: routePrefix.slice(0, -1) + m.path
+			})) };
+		}
+		const allMatches = [];
+		const rawDefault = await this.default.grep(pattern, path, glob);
+		if (rawDefault.error) return rawDefault;
+		allMatches.push(...rawDefault.matches || []);
+		for (const [routePrefix, backend] of Object.entries(this.routes)) {
+			const raw = await backend.grep(pattern, "/", glob);
+			if (raw.error) return raw;
+			const matches = (raw.matches || []).map((m) => ({
+				...m,
+				path: routePrefix.slice(0, -1) + m.path
+			}));
+			allMatches.push(...matches);
+		}
+		return { matches: allMatches };
+	}
+	/**
+	* Structured glob matching returning FileInfo objects.
+	*/
+	async glob(pattern, path = "/") {
+		const results = [];
+		for (const [routePrefix, backend] of this.sortedRoutes) if (path.startsWith(routePrefix.replace(/\/$/, ""))) {
+			const searchPath = path.substring(routePrefix.length - 1);
+			const result = await backend.glob(pattern, searchPath || "/");
+			if (result.error) return result;
+			return { files: (result.files || []).map((fi) => ({
+				...fi,
+				path: routePrefix.slice(0, -1) + fi.path
+			})) };
+		}
+		const defaultResult = await this.default.glob(pattern, path);
+		if (defaultResult.error) return defaultResult;
+		results.push(...defaultResult.files || []);
+		for (const [routePrefix, backend] of Object.entries(this.routes)) {
+			const result = await backend.glob(pattern, "/");
+			if (result.error) continue;
+			const files = (result.files || []).map((fi) => ({
+				...fi,
+				path: routePrefix.slice(0, -1) + fi.path
+			}));
+			results.push(...files);
+		}
+		results.sort((a, b) => a.path.localeCompare(b.path));
+		return { files: 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 = Array.from({ length: files.length }, () => null);
+		const batchesByBackend = /* @__PURE__ */ new Map();
+		for (let idx = 0; idx < files.length; idx++) {
+			const [path, content] = files[idx];
+			const [backend, strippedPath] = this.getBackendAndKey(path);
+			if (!batchesByBackend.has(backend)) batchesByBackend.set(backend, []);
+			batchesByBackend.get(backend).push({
+				idx,
+				path: strippedPath,
+				content
+			});
+		}
+		for (const [backend, batch] of batchesByBackend) {
+			if (!backend.uploadFiles) throw new Error("Backend does not support uploadFiles");
+			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 = Array.from({ length: paths.length }, () => null);
+		const batchesByBackend = /* @__PURE__ */ new Map();
+		for (let idx = 0; idx < paths.length; idx++) {
+			const path = paths[idx];
+			const [backend, strippedPath] = this.getBackendAndKey(path);
+			if (!batchesByBackend.has(backend)) batchesByBackend.set(backend, []);
+			batchesByBackend.get(backend).push({
+				idx,
+				path: strippedPath
+			});
+		}
+		for (const [backend, batch] of batchesByBackend) {
+			if (!backend.downloadFiles) throw new Error("Backend does not support downloadFiles");
+			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/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
+*/
+const INT_FORMATTER = new Intl.NumberFormat("en-US");
+/**
+* Tools that should be excluded from the large result eviction logic.
+*
+* This array contains tools that should NOT have their results evicted to the filesystem
+* when they exceed token limits. Tools are excluded for different reasons:
+*
+* 1. Tools with built-in truncation (ls, glob, grep):
+*    These tools truncate their own output when it becomes too large. When these tools
+*    produce truncated output due to many matches, it typically indicates the query
+*    needs refinement rather than full result preservation. In such cases, the truncated
+*    matches are potentially more like noise and the LLM should be prompted to narrow
+*    its search criteria instead.
+*
+* 2. Tools with problematic truncation behavior (read_file):
+*    read_file is tricky to handle as the failure mode here is single long lines
+*    (e.g., imagine a jsonl file with very long payloads on each line). If we try to
+*    truncate the result of read_file, the agent may then attempt to re-read the
+*    truncated file using read_file again, which won't help.
+*
+* 3. Tools that never exceed limits (edit_file, write_file):
+*    These tools return minimal confirmation messages and are never expected to produce
+*    output large enough to exceed token limits, so checking them would be unnecessary.
+*/
+/**
+* All tool names registered by FilesystemMiddleware.
+* This is the single source of truth — used by createDeepAgent to detect
+* collisions with user-supplied tools at construction time.
+*/
+const FILESYSTEM_TOOL_NAMES = [
+	"ls",
+	"read_file",
+	"write_file",
+	"edit_file",
+	"glob",
+	"grep",
+	"execute"
+];
+const TOOLS_EXCLUDED_FROM_EVICTION = [
+	"ls",
+	"glob",
+	"grep",
+	"read_file",
+	"edit_file",
+	"write_file"
+];
+/**
+* Maximum size for binary (non-text) files read via read_file, in bytes.
+* Base64-encoded content is ~33% larger, so 10MB raw ≈ 13.3MB in context.
+* This keeps inline multimodal payloads within all major provider limits.
+*/
+const MAX_BINARY_READ_SIZE_BYTES = 10 * 1024 * 1024;
+/**
+* Template for truncation message in read_file.
+* {file_path} will be filled in at runtime.
+*/
+const READ_FILE_TRUNCATION_MSG = `
+
+[Output was truncated due to size limits. The file content is very large. Consider reformatting the file to make it easier to navigate. For example, if this is JSON, use execute(command='jq . {file_path}') to pretty-print it with line breaks. For other formats, you can use appropriate formatting tools to split long lines.]`;
+/**
+* Message template for evicted tool results.
+*/
+const TOO_LARGE_TOOL_MSG = context`
+  Tool result too large, the result of this tool call {tool_call_id} was saved in the filesystem at this path: {file_path}
+  You can read the result from the filesystem by using the read_file tool, but make sure to only read part of the result at a time.
+  You can do this by specifying an offset and limit in the read_file tool call.
+  For example, to read the first ${100} lines, you can use the read_file tool with offset=0 and limit=${100}.
+
+  Here is a preview showing the head and tail of the result (lines of the form
+  ... [N lines truncated] ...
+  indicate omitted lines in the middle of the content):
+
+  {content_sample}
+`;
+/**
+* Message template for evicted HumanMessages.
+*/
+const TOO_LARGE_HUMAN_MSG = `Message content too large and was saved to the filesystem at: {file_path}
+
+You can read the full content using the read_file tool with pagination (offset and limit parameters).
+
+Here is a preview showing the head and tail of the content:
+
+{content_sample}`;
+/**
+* Extract text content from a message.
+*
+* For string content, returns it directly. For array content (mixed block types
+* like text + image), joins all text blocks. Returns empty string if no text found.
+*/
+function extractTextFromMessage(message) {
+	if (typeof message.content === "string") return message.content;
+	if (Array.isArray(message.content)) return message.content.filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text).join("\n");
+	return String(message.content);
+}
+/**
+* Build replacement content for an evicted HumanMessage, preserving non-text blocks.
+*
+* For plain string content, returns the replacement text directly. For list content
+* with mixed block types (e.g., text + image), replaces all text blocks with a single
+* text block containing the replacement text while keeping non-text blocks intact.
+*/
+function buildEvictedHumanContent(message, replacementText) {
+	if (typeof message.content === "string") return replacementText;
+	if (Array.isArray(message.content)) {
+		const mediaBlocks = message.content.filter((block) => typeof block === "object" && block !== null && block.type !== "text");
+		if (mediaBlocks.length === 0) return replacementText;
+		return [{
+			type: "text",
+			text: replacementText
+		}, ...mediaBlocks];
+	}
+	return replacementText;
+}
+/**
+* Build a truncated HumanMessage for the model request.
+*
+* Computes a preview from the full content still in state and returns a
+* lightweight replacement the model will see. Pure string computation — no
+* backend I/O.
+*/
+function buildTruncatedHumanMessage(message, filePath) {
+	const contentSample = createContentPreview(extractTextFromMessage(message));
+	return new HumanMessage({
+		content: buildEvictedHumanContent(message, TOO_LARGE_HUMAN_MSG.replace("{file_path}", filePath).replace("{content_sample}", contentSample)),
+		id: message.id,
+		additional_kwargs: { ...message.additional_kwargs },
+		response_metadata: { ...message.response_metadata }
+	});
+}
+/**
+* Create a preview of content showing head and tail with truncation marker.
+*
+* @param contentStr - The full content string to preview.
+* @param headLines - Number of lines to show from the start (default: 5).
+* @param tailLines - Number of lines to show from the end (default: 5).
+* @returns Formatted preview string with line numbers.
+*/
+function createContentPreview(contentStr, headLines = 5, tailLines = 5) {
+	const lines = contentStr.split("\n");
+	if (lines.length <= headLines + tailLines) return formatContentWithLineNumbers(lines.map((line) => line.substring(0, 1e3)), 1);
+	const head = lines.slice(0, headLines).map((line) => line.substring(0, 1e3));
+	const tail = lines.slice(-tailLines).map((line) => line.substring(0, 1e3));
+	const headSample = formatContentWithLineNumbers(head, 1);
+	const truncationNotice = `\n... [${lines.length - headLines - tailLines} lines truncated] ...\n`;
+	const tailSample = formatContentWithLineNumbers(tail, lines.length - tailLines + 1);
+	return headSample + truncationNotice + tailSample;
+}
+/**
+* Zod schema for legacy FileDataV1 (content as line array).
+*/
+const FileDataV1Schema = z.object({
+	content: z.array(z.string()),
+	created_at: z.string(),
+	modified_at: z.string()
+});
+/**
+* Zod schema for FileDataV2 (content as string for text or Uint8Array for binary).
+*/
+const FileDataV2Schema = z.object({
+	content: z.union([z.string(), z.instanceof(Uint8Array)]),
+	mimeType: z.string(),
+	created_at: z.string(),
+	modified_at: z.string()
+});
+/**
+* Zod v3 schema for FileData (re-export from backends)
+*/
+const FileDataSchema = z.union([FileDataV1Schema, FileDataV2Schema]);
+/**
+* Reducer for files state that merges file updates with support for deletions.
+* When a file value is null, the file is deleted from state.
+* When a file value is non-null, it is added or updated in state.
+*
+* This reducer enables concurrent updates from parallel subagents by properly
+* merging their file changes instead of requiring LastValue semantics.
+*
+* @param current - The current files record (from state)
+* @param update - The new files record (from a subagent update), with null values for deletions
+* @returns Merged files record with deletions applied
+*/
+function fileDataReducer(current, update) {
+	if (update === void 0) return current || {};
+	if (current === void 0) {
+		const result = {};
+		for (const [key, value] of Object.entries(update)) if (value !== null) result[key] = value;
+		return result;
+	}
+	const result = { ...current };
+	for (const [key, value] of Object.entries(update)) 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.
+*
+* Uses ReducedValue for files to allow concurrent updates from parallel subagents.
+*/
+const FilesystemStateSchema = new StateSchema({ files: new ReducedValue(z.record(z.string(), FileDataSchema).default(() => ({})), {
+	inputSchema: z.record(z.string(), FileDataSchema.nullable()).optional(),
+	reducer: fileDataReducer
+}) });
+/**
+* Throw a permission-denied error if `path` is denied under `rules`.
+*
+* No-op when `rules` is empty (permissive default). Paths that fail
+* `validatePath` are silently skipped — the tool's own input validation
+* will surface a better error.
+*
+* @internal
+*/
+function enforcePermission(rules, operation, path) {
+	if (rules.length === 0) return;
+	const canonical = validatePath(path);
+	if (decidePathAccess(rules, operation, canonical) === "deny") throw new Error(`Error: permission denied for ${operation} on ${canonical}`);
+}
+/**
+* Filter a list of filesystem entries to those the rules permit.
+*
+* `getPath` extracts the absolute path from each entry. Entries with
+* unparsable paths are included (not silently dropped). Returns the
+* original array unchanged when `rules` is empty.
+*
+* @internal
+*/
+function filterByPermissions(entries, rules, operation, getPath) {
+	if (rules.length === 0) return entries;
+	return entries.filter((entry) => {
+		try {
+			return decidePathAccess(rules, operation, validatePath(getPath(entry))) !== "deny";
+		} catch {
+			return true;
+		}
+	});
+}
+const FILESYSTEM_SYSTEM_PROMPT = context`
+  ## Following Conventions
+
+  - Read files before editing — understand existing content before making changes
+  - Mimic existing style, naming conventions, and patterns
+
+  ## Filesystem Tools \`ls\`, \`read_file\`, \`write_file\`, \`edit_file\`, \`glob\`, \`grep\`
+
+  You have access to a filesystem which you can interact with using these tools.
+  All file paths must start with a /.
+
+  - ls: list files in a directory (requires absolute path)
+  - read_file: read a file from the filesystem
+  - write_file: write to a file in the filesystem
+  - edit_file: edit a file in the filesystem
+  - glob: find files matching a pattern (e.g., "**/*.py")
+  - grep: search for text within files
+`;
+const LS_TOOL_DESCRIPTION = context`
+  Lists all files in a directory.
+
+  This is useful for exploring the filesystem and finding the right file to read or edit.
+  You should almost ALWAYS use this tool before using the read_file or edit_file tools.
+`;
+const READ_FILE_TOOL_DESCRIPTION = context`
+  Reads a file from the filesystem.
+
+  Assume this tool is able to read all files. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+  Usage:
+  - By default, it reads up to ${100} lines starting from the beginning of the file
+  - **IMPORTANT for large files and codebase exploration**: Use pagination with offset and limit parameters to avoid context overflow
+    - First scan: read_file(path, limit=${100}) to see file structure
+    - Read more sections: read_file(path, offset=${100}, limit=200) for next 200 lines
+    - Only omit limit (read full file) when necessary for editing
+  - Specify offset and limit: read_file(path, offset=0, limit=${100}) reads first ${100} lines
+  - Results are returned using cat -n format, with line numbers starting at 1
+- Lines longer than ${INT_FORMATTER.format(MAX_LINE_LENGTH)} characters will be split into multiple lines with continuation markers (e.g., 5.1, 5.2, etc.). When you specify a limit, these continuation lines count towards the limit.
+  - You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.
+  - If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
+  - You should ALWAYS make sure a file has been read before editing it.
+`;
+const WRITE_FILE_TOOL_DESCRIPTION = context`
+  Writes to a new file in the filesystem.
+
+  Usage:
+  - The write_file tool will create a new file.
+  - Prefer to edit existing files (with the edit_file tool) over creating new ones when possible.
+`;
+const EDIT_FILE_TOOL_DESCRIPTION = context`
+  Performs exact string replacements in files.
+
+  Usage:
+  - You must read the file before editing. This tool will error if you attempt an edit without reading the file first.
+  - When editing, preserve the exact indentation (tabs/spaces) from the read output. Never include line number prefixes in old_string or new_string.
+  - ALWAYS prefer editing existing files over creating new ones.
+  - Only use emojis if the user explicitly requests it.
+`;
 const GLOB_TOOL_DESCRIPTION = context`
   Find files matching a glob pattern.
 
@@ -1166,13 +1524,14 @@ const EXECUTION_SYSTEM_PROMPT = context`
 * Create ls tool using backend.
 */
 function createLsTool(backend, options) {
-	const { customDescription } = options;
+	const { customDescription, permissions } = options;
 	return tool(async (input, runtime) => {
+		enforcePermission(permissions, "read", input.path ?? "/");
 		const resolvedBackend = await resolveBackend(backend, runtime);
 		const path = input.path || "/";
 		const lsResult = await resolvedBackend.ls(path);
 		if (lsResult.error) return `Error listing files: ${lsResult.error}`;
-		const infos = lsResult.files || [];
+		const infos = filterByPermissions(lsResult.files ?? [], permissions, "read", (info) => info.path);
 		if (infos.length === 0) return `No files found in ${path}`;
 		const lines = [];
 		for (const info of infos) if (info.is_dir) lines.push(`${info.path} (directory)`);
@@ -1193,8 +1552,9 @@ function createLsTool(backend, options) {
 * Create read_file tool using backend.
 */
 function createReadFileTool(backend, options) {
-	const { customDescription, toolTokenLimitBeforeEvict } = options;
+	const { customDescription, toolTokenLimitBeforeEvict, permissions } = options;
 	return tool(async (input, runtime) => {
+		enforcePermission(permissions, "read", input.file_path);
 		const resolvedBackend = await resolveBackend(backend, runtime);
 		const { file_path, offset = 0, limit = 100 } = input;
 		const readResult = await resolvedBackend.read(file_path, offset, limit);
@@ -1269,8 +1629,9 @@ function createReadFileTool(backend, options) {
 * Create write_file tool using backend.
 */
 function createWriteFileTool(backend, options) {
-	const { customDescription } = options;
+	const { customDescription, permissions } = options;
 	return tool(async (input, runtime) => {
+		enforcePermission(permissions, "write", input.file_path);
 		const resolvedBackend = await resolveBackend(backend, runtime);
 		const { file_path, content } = input;
 		const result = await resolvedBackend.write(file_path, content);
@@ -1299,8 +1660,9 @@ function createWriteFileTool(backend, options) {
 * Create edit_file tool using backend.
 */
 function createEditFileTool(backend, options) {
-	const { customDescription } = options;
+	const { customDescription, permissions } = options;
 	return tool(async (input, runtime) => {
+		enforcePermission(permissions, "write", input.file_path);
 		const resolvedBackend = await resolveBackend(backend, runtime);
 		const { file_path, old_string, new_string, replace_all = false } = input;
 		const result = await resolvedBackend.edit(file_path, old_string, new_string, replace_all);
@@ -1331,13 +1693,14 @@ function createEditFileTool(backend, options) {
 * Create glob tool using backend.
 */
 function createGlobTool(backend, options) {
-	const { customDescription } = options;
+	const { customDescription, permissions } = options;
 	return tool(async (input, runtime) => {
+		enforcePermission(permissions, "read", input.path ?? "/");
 		const resolvedBackend = await resolveBackend(backend, runtime);
 		const { pattern, path = "/" } = input;
 		const globResult = await resolvedBackend.glob(pattern, path);
 		if (globResult.error) return `Error finding files: ${globResult.error}`;
-		const infos = globResult.files || [];
+		const infos = filterByPermissions(globResult.files ?? [], permissions, "read", (info) => info.path);
 		if (infos.length === 0) return `No files found matching pattern '${pattern}'`;
 		const result = truncateIfTooLong(infos.map((info) => info.path));
 		if (Array.isArray(result)) return result.join("\n");
@@ -1355,13 +1718,14 @@ function createGlobTool(backend, options) {
 * Create grep tool using backend.
 */
 function createGrepTool(backend, options) {
-	const { customDescription } = options;
+	const { customDescription, permissions } = options;
 	return tool(async (input, runtime) => {
+		enforcePermission(permissions, "read", input.path ?? "/");
 		const resolvedBackend = await resolveBackend(backend, runtime);
 		const { pattern, path = "/", glob = null } = input;
 		const result = await resolvedBackend.grep(pattern, path, glob);
 		if (result.error) return result.error;
-		const matches = result.matches ?? [];
+		const matches = filterByPermissions(result.matches ?? [], permissions, "read", (m) => m.path);
 		if (matches.length === 0) return `No matches found for pattern '${pattern}'`;
 		const lines = [];
 		let currentFile = null;
@@ -1389,10 +1753,11 @@ function createGrepTool(backend, options) {
 * Create execute tool using backend.
 */
 function createExecuteTool(backend, options) {
-	const { customDescription } = options;
+	const { customDescription, permissions } = options;
 	return tool(async (input, runtime) => {
 		const resolvedBackend = await resolveBackend(backend, runtime);
 		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.";
+		if (permissions.length > 0 && !allPathsScopedToRoutes(permissions, resolvedBackend)) return "Error: Execution not available. Filesystem permissions cannot be used with a backend that supports command execution because shell commands can access any path, making path-based rules ineffective.";
 		const result = await resolvedBackend.execute(input.command);
 		const parts = [result.output];
 		if (result.exitCode !== null) {
@@ -1408,22 +1773,53 @@ function createExecuteTool(backend, options) {
 	});
 }
 /**
+* Returns true only when backend exposes route prefixes (CompositeBackend) and
+* every permission path is scoped under one of them.
+*/
+function allPathsScopedToRoutes(permissions, backend) {
+	if (!CompositeBackend.isInstance(backend)) return false;
+	const prefixes = backend.routePrefixes;
+	if (prefixes.length === 0) return false;
+	return permissions.every((rule) => rule.paths.every((path) => prefixes.some((prefix) => path.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`))));
+}
+/**
 * Create filesystem middleware with all tools and features.
 */
 function createFilesystemMiddleware(options = {}) {
-	const { backend = (runtime) => new StateBackend(runtime), systemPrompt: customSystemPrompt = null, customToolDescriptions = null, toolTokenLimitBeforeEvict = 2e4, humanMessageTokenLimitBeforeEvict = 5e4 } = options;
+	const { backend = (runtime) => new StateBackend(runtime), systemPrompt: customSystemPrompt = null, customToolDescriptions = null, toolTokenLimitBeforeEvict = 2e4, humanMessageTokenLimitBeforeEvict = 5e4, permissions = [] } = options;
+	if (permissions.length > 0) validatePermissionPaths(permissions);
+	if (permissions.length > 0 && typeof backend !== "function" && isSandboxBackend(backend) && !allPathsScopedToRoutes(permissions, backend)) throw new Error("Filesystem permissions cannot be used with a backend that supports command execution. Shell commands can access any path, making path-based rules ineffective. Either remove permissions, use a backend without execution support, or use a CompositeBackend with all permission paths scoped to a route prefix.");
 	const baseSystemPrompt = customSystemPrompt || FILESYSTEM_SYSTEM_PROMPT;
 	const allToolsByName = {
-		ls: createLsTool(backend, { customDescription: customToolDescriptions?.ls }),
+		ls: createLsTool(backend, {
+			customDescription: customToolDescriptions?.ls,
+			permissions
+		}),
 		read_file: createReadFileTool(backend, {
 			customDescription: customToolDescriptions?.read_file,
-			toolTokenLimitBeforeEvict
+			toolTokenLimitBeforeEvict,
+			permissions
+		}),
+		write_file: createWriteFileTool(backend, {
+			customDescription: customToolDescriptions?.write_file,
+			permissions
+		}),
+		edit_file: createEditFileTool(backend, {
+			customDescription: customToolDescriptions?.edit_file,
+			permissions
+		}),
+		glob: createGlobTool(backend, {
+			customDescription: customToolDescriptions?.glob,
+			permissions
+		}),
+		grep: createGrepTool(backend, {
+			customDescription: customToolDescriptions?.grep,
+			permissions
 		}),
-		write_file: createWriteFileTool(backend, { customDescription: customToolDescriptions?.write_file }),
-		edit_file: createEditFileTool(backend, { customDescription: customToolDescriptions?.edit_file }),
-		glob: createGlobTool(backend, { customDescription: customToolDescriptions?.glob }),
-		grep: createGrepTool(backend, { customDescription: customToolDescriptions?.grep }),
-		execute: createExecuteTool(backend, { customDescription: customToolDescriptions?.execute })
+		execute: createExecuteTool(backend, {
+			customDescription: customToolDescriptions?.execute,
+			permissions
+		})
 	};
 	return createMiddleware({
 		name: "FilesystemMiddleware",
@@ -1883,7 +2279,14 @@ function createTaskTool(options) {
 		const subagent = subagentGraphs[subagent_type];
 		const subagentState = filterStateForSubagent(getCurrentTaskInput());
 		subagentState.messages = [new HumanMessage$1({ content: description })];
-		const result = await subagent.invoke(subagentState, config);
+		const subagentConfig = {
+			...config,
+			configurable: {
+				...config.configurable,
+				ls_agent_type: "subagent"
+			}
+		};
+		const result = await subagent.invoke(subagentState, subagentConfig);
 		if (!config.toolCall?.id) {
 			if (result.structuredResponse != null) return JSON.stringify(result.structuredResponse);
 			const messages = result.messages;
@@ -2339,9 +2742,23 @@ function createMemoryMiddleware(options) {
 * ```
 */
 const MAX_SKILL_FILE_SIZE = 10 * 1024 * 1024;
+const DEFAULT_SKILL_READ_LINE_LIMIT = 1e3;
 const MAX_SKILL_NAME_LENGTH = 64;
 const MAX_SKILL_DESCRIPTION_LENGTH = 1024;
 /**
+* File extensions a skill module entrypoint may use.
+*/
+const SKILL_MODULE_EXTENSIONS = [
+	".js",
+	".mjs",
+	".cjs",
+	".ts",
+	".mts",
+	".cts",
+	".jsx",
+	".tsx"
+];
+/**
 * Zod schema for a single skill metadata entry.
 */
 const SkillMetadataEntrySchema = z$1.object({
@@ -2351,7 +2768,8 @@ const SkillMetadataEntrySchema = z$1.object({
 	license: z$1.string().nullable().optional(),
 	compatibility: z$1.string().nullable().optional(),
 	metadata: z$1.record(z$1.string(), z$1.string()).optional(),
-	allowedTools: z$1.array(z$1.string()).optional()
+	allowedTools: z$1.array(z$1.string()).optional(),
+	module: z$1.string().optional()
 });
 /**
 * Reducer for skillsMetadata that merges arrays from parallel subagents.
@@ -2383,48 +2801,49 @@ const SkillsStateSchema = new StateSchema({
 /**
 * Skills System Documentation prompt template.
 */
-const SKILLS_SYSTEM_PROMPT = `
-## Skills System
+const SKILLS_SYSTEM_PROMPT = context`
+  ## Skills System
 
-You have access to a skills library that provides specialized capabilities and domain knowledge.
+  You have access to a skills library that provides specialized capabilities and domain knowledge.
 
-{skills_locations}
+  {skills_locations}
 
-**Available Skills:**
+  **Available Skills:**
 
-{skills_list}
+  {skills_list}
 
-**How to Use Skills (Progressive Disclosure):**
+  **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:
+  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 scripts, configs, or reference docs - use absolute paths
+  1. **Recognize when a skill applies**: Check if the user's task matches any skill's description
+  2. **Read the skill's full instructions**: Use \`read_file\` on the path shown in the skill list above.
+     Pass \`limit=${DEFAULT_SKILL_READ_LINE_LIMIT}\` since the default of ${100} lines is too small for most skill files.
+  3. **Follow the skill's instructions**: SKILL.md contains step-by-step workflows, best practices, and examples
+  4. **Access supporting files**: Skills may include scripts, configs, or reference docs - use absolute paths
 
-**When to Use Skills:**
-- When the user's request matches a skill's domain (e.g., "research X" → web-research skill)
-- When you need specialized knowledge or structured workflows
-- When a skill provides proven patterns for complex tasks
+  **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
+  **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 scripts or other executable files. Always use absolute paths from the skill list.
+  **Executing Skill Scripts:**
+  Skills may contain scripts or other executable files. Always use absolute paths from the skill list.
 
-**Example Workflow:**
+  **Example Workflow:**
 
-User: "Can you research the latest developments in quantum computing?"
+  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
+  1. Check available skills above → See "web-research" skill with its full path
+  2. Read the full skill file: \`read_file(path, limit=${DEFAULT_SKILL_READ_LINE_LIMIT})\`
+  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!
+  Remember: Skills are tools to make you more capable and consistent. When in doubt, check if a skill exists for the task!
 `;
 /**
 * Validate skill name per Agent Skills specification.
@@ -2575,7 +2994,8 @@ function parseSkillMetadataFromContent(content, skillPath, directoryName) {
 		metadata: validateMetadata(frontmatterData.metadata ?? {}, skillPath),
 		license: String(frontmatterData.license ?? "").trim() || null,
 		compatibility: compatibilityStr,
-		allowedTools
+		allowedTools,
+		module: validateModulePath(frontmatterData.module)
 	};
 }
 /**
@@ -2648,10 +3068,38 @@ function formatSkillsList(skills, sources) {
 		lines.push(descLine);
 		if (skill.allowedTools && skill.allowedTools.length > 0) lines.push(`  → Allowed tools: ${skill.allowedTools.join(", ")}`);
 		lines.push(`  → Read \`${skill.path}\` for full instructions`);
+		if (skill.module !== void 0) lines.push(`  → Import: \`await import("@/skills/${skill.name}")\``);
 	}
 	return lines.join("\n");
 }
 /**
+* Returns true when `value` ends with a recognized skill module extension.
+*/
+function endsWithModuleExtension(value) {
+	for (const ext of SKILL_MODULE_EXTENSIONS) if (value.endsWith(ext)) return true;
+	return false;
+}
+/**
+* Validate and normalize the `module` frontmatter key from a `SKILL.md`.
+*
+* Returns the normalized path (e.g. `"index.ts"`, `"lib/entry.js"`) or
+* `undefined` when the key is absent, empty, non-string, absolute, contains
+* path traversal, or uses an unsupported extension. Invalid values silently
+* degrade the skill to prose-only.
+*/
+function validateModulePath(raw) {
+	if (raw === null || raw === void 0) return;
+	if (typeof raw !== "string") return;
+	const stripped = raw.trim();
+	if (stripped === "") return;
+	const normalized = stripped.startsWith("./") ? stripped.slice(2) : stripped;
+	if (normalized.startsWith("/")) return;
+	if (normalized === ".." || normalized.startsWith("../") || normalized.includes("/../") || normalized.endsWith("/..")) return;
+	if (normalized.endsWith(".d.ts") || normalized.endsWith(".d.mts") || normalized.endsWith(".d.cts")) return;
+	if (!endsWithModuleExtension(normalized)) return;
+	return normalized;
+}
+/**
 * Create backend-agnostic middleware for loading and exposing agent skills.
 *
 * This middleware loads skills from configurable backend sources and injects
@@ -3151,6 +3599,7 @@ function createSummarizationMiddleware(options) {
 	*/
 	async function getChatModel() {
 		if (cachedModel) return cachedModel;
+		if (!model) throw new Error("Summarization middleware could not resolve a model. Provide `options.model` or ensure `request.model` is present.");
 		if (typeof model === "string") cachedModel = await initChatModel(model);
 		else cachedModel = model;
 		return cachedModel;
@@ -3581,7 +4030,7 @@ function createSummarizationMiddleware(options) {
 			/**
 			* Resolve the chat model and get max input tokens from its profile.
 			*/
-			const resolvedModel = await getChatModel();
+			const resolvedModel = request.model ?? await getChatModel();
 			const maxInputTokens = getMaxInputTokens(resolvedModel);
 			applyModelDefaults(resolvedModel);
 			/**
@@ -4190,6 +4639,13 @@ function createAsyncSubAgentMiddleware(options) {
 * StoreBackend: Adapter for LangGraph's BaseStore (persistent, cross-thread).
 */
 const NAMESPACE_COMPONENT_RE = /^[A-Za-z0-9\-_.@+:~]+$/;
+function getObjectRecord(value) {
+	return value != null && typeof value === "object" ? value : void 0;
+}
+function getAssistantIdFromRecord(value) {
+	const assistantId = value?.assistant_id ?? value?.assistantId;
+	return typeof assistantId === "string" && assistantId.length > 0 ? assistantId : void 0;
+}
 /**
 * Validate a namespace array.
 *
@@ -4222,536 +4678,236 @@ function validateNamespace(namespace) {
 */
 var StoreBackend = class {
 	stateAndStore;
+	storeOverride;
 	_namespace;
-	fileFormat;
-	constructor(stateAndStoreOrOptions, options) {
-		let opts;
-		if (stateAndStoreOrOptions != null && typeof stateAndStoreOrOptions === "object" && "state" in stateAndStoreOrOptions) {
-			this.stateAndStore = stateAndStoreOrOptions;
-			opts = options;
-		} else {
-			this.stateAndStore = void 0;
-			opts = stateAndStoreOrOptions;
-		}
-		if (opts?.namespace) this._namespace = validateNamespace(opts.namespace);
-		this.fileFormat = opts?.fileFormat ?? "v2";
-	}
-	/**
-	* Get the BaseStore instance for persistent storage operations.
-	*
-	* In legacy mode, reads from the injected {@link StateAndStore}.
-	* In zero-arg mode, retrieves the store from the LangGraph execution
-	* context via {@link getLangGraphStore}.
-	*
-	* @returns BaseStore instance
-	* @throws Error if no store is available in either mode
-	*/
-	getStore() {
-		if (this.stateAndStore) {
-			const store = this.stateAndStore.store;
-			if (!store) throw new Error("Store is required but not available in runtime");
-			return store;
-		}
-		const store = getStore();
-		if (!store) throw new Error("Store is required but not available in LangGraph execution context. Ensure the graph was configured with a store.");
-		return store;
-	}
-	/**
-	* Get the namespace for store operations.
-	*
-	* Resolution order:
-	* 1. Explicit namespace from constructor options (both modes)
-	* 2. Legacy mode: `[assistantId, "filesystem"]` fallback from {@link StateAndStore}
-	* 3. Zero-arg mode without namespace: `["filesystem"]` with a deprecation warning
-	*    nudging callers to pass an explicit namespace
-	* 4. Legacy mode without assistantId: `["filesystem"]`
-	*/
-	getNamespace() {
-		if (this._namespace) return this._namespace;
-		if (this.stateAndStore) {
-			const assistantId = this.stateAndStore.assistantId;
-			if (assistantId) return [assistantId, "filesystem"];
-		}
-		return ["filesystem"];
-	}
-	/**
-	* 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 !== void 0 && (Array.isArray(value.content) || typeof value.content === "string" || ArrayBuffer.isView(value.content))) || typeof value.created_at !== "string" || typeof value.modified_at !== "string") throw new Error(`Store item does not contain valid FileData fields. Got keys: ${Object.keys(value).join(", ")}`);
-		return {
-			content: value.content,
-			...value.mimeType ? { mimeType: value.mimeType } : {},
-			created_at: value.created_at,
-			modified_at: value.modified_at
-		};
-	}
-	/**
-	* Convert FileData to a value suitable for store.put().
-	*
-	* @param fileData - The FileData to convert
-	* @returns Object with content, mimeType, created_at, and modified_at fields
-	*/
-	convertFileDataToStoreValue(fileData) {
-		return {
-			content: fileData.content,
-			..."mimeType" in fileData ? { mimeType: fileData.mimeType } : {},
-			created_at: fileData.created_at,
-			modified_at: fileData.modified_at
-		};
-	}
-	/**
-	* 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 LsResult with list of FileInfo objects on success or error on failure.
-	*          Directories have a trailing / in their path and is_dir=true.
-	*/
-	async ls(path) {
-		const store = this.getStore();
-		const namespace = this.getNamespace();
-		const items = await this.searchStorePaginated(store, namespace);
-		const infos = [];
-		const subdirs = /* @__PURE__ */ new Set();
-		const normalizedPath = path.endsWith("/") ? path : path + "/";
-		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 = isFileDataV1(fd) ? fd.content.join("\n").length : isFileDataBinary(fd) ? fd.content.byteLength : fd.content.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 { files: infos };
-	}
-	/**
-	* Read file content.
-	*
-	* Text files are paginated by line offset/limit.
-	* Binary files return full Uint8Array content (offset/limit ignored).
-	*
-	* @param filePath - Absolute file path
-	* @param offset - Line offset to start reading from (0-indexed)
-	* @param limit - Maximum number of lines to read
-	* @returns ReadResult with content on success or error on failure
-	*/
-	async read(filePath, offset = 0, limit = 500) {
-		try {
-			const readRawResult = await this.readRaw(filePath);
-			if (readRawResult.error || !readRawResult.data) return { error: readRawResult.error || "File data not found" };
-			const fileDataV2 = migrateToFileDataV2(readRawResult.data, filePath);
-			if (!isTextMimeType(fileDataV2.mimeType)) return {
-				content: fileDataV2.content,
-				mimeType: fileDataV2.mimeType
-			};
-			if (typeof fileDataV2.content !== "string") return { error: `File '${filePath}' has binary content but text MIME type` };
-			return {
-				content: fileDataV2.content.split("\n").slice(offset, offset + limit).join("\n"),
-				mimeType: fileDataV2.mimeType
-			};
-		} catch (e) {
-			return { error: e.message };
-		}
-	}
-	/**
-	* Read file content as raw FileData.
-	*
-	* @param filePath - Absolute file path
-	* @returns ReadRawResult with raw file data on success or error on failure
-	*/
-	async readRaw(filePath) {
-		const store = this.getStore();
-		const namespace = this.getNamespace();
-		const item = await store.get(namespace, filePath);
-		if (!item) return { error: `File '${filePath}' not found` };
-		return { data: 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 mimeType = getMimeType(filePath);
-		const fileData = createFileData(content, void 0, this.fileFormat, mimeType);
-		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}` };
+	fileFormat;
+	constructor(stateAndStoreOrOptions, options) {
+		let opts;
+		if (stateAndStoreOrOptions != null && typeof stateAndStoreOrOptions === "object" && "state" in stateAndStoreOrOptions) {
+			this.stateAndStore = stateAndStoreOrOptions;
+			opts = options;
+		} else {
+			this.stateAndStore = void 0;
+			opts = stateAndStoreOrOptions;
 		}
+		if (Array.isArray(opts?.namespace)) this._namespace = validateNamespace(opts.namespace);
+		else if (opts?.namespace) this._namespace = opts.namespace;
+		this.storeOverride = opts?.store;
+		this.fileFormat = opts?.fileFormat ?? "v2";
 	}
 	/**
-	* Search file contents for a literal text pattern.
-	* Binary files are skipped.
+	* Get the BaseStore instance for persistent storage operations.
+	*
+	* In legacy mode, reads from the injected {@link StateAndStore}.
+	* In zero-arg mode, retrieves the store from the LangGraph execution
+	* context via {@link getLangGraphStore}.
+	*
+	* @returns BaseStore instance
+	* @throws Error if no store is available in either mode
 	*/
-	async grep(pattern, path = "/", 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;
+	getStore() {
+		if (this.stateAndStore) {
+			const store = this.stateAndStore.store;
+			if (!store) throw new Error("Store is required but not available in runtime");
+			return store;
 		}
-		return { matches: grepMatchesFromFiles(files, pattern, path, glob) };
+		if (this.storeOverride) return this.storeOverride;
+		const store = getStore();
+		if (!store) throw new Error("Store is required but not available in LangGraph execution context. Ensure the graph was configured with a store.");
+		return store;
 	}
 	/**
-	* Structured glob matching returning FileInfo objects.
+	* Get the current graph state when available.
 	*/
-	async glob(pattern, path = "/") {
-		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);
+	getState() {
+		if (this.stateAndStore) return this.stateAndStore.state;
+		try {
+			return getCurrentTaskInput();
 		} catch {
-			continue;
+			return;
 		}
-		const result = globSearchFiles(files, pattern, path);
-		if (result === "No files found") return { files: [] };
-		const paths = result.split("\n");
-		const infos = [];
-		for (const p of paths) {
-			const fd = files[p];
-			const size = fd ? isFileDataV1(fd) ? fd.content.join("\n").length : isFileDataBinary(fd) ? fd.content.byteLength : fd.content.length : 0;
-			infos.push({
-				path: p,
-				is_dir: false,
-				size,
-				modified_at: fd?.modified_at || ""
-			});
-		}
-		return { files: infos };
 	}
 	/**
-	* Upload multiple files.
-	*
-	* @param files - List of [path, content] tuples to upload
-	* @returns List of FileUploadResponse objects, one per input file
+	* Get the most relevant runnable config for namespace resolution.
 	*/
-	async uploadFiles(files) {
-		const store = this.getStore();
-		const namespace = this.getNamespace();
-		const responses = [];
-		for (const [path, content] of files) try {
-			const mimeType = getMimeType(path);
-			const isBinary = this.fileFormat === "v2" && !isTextMimeType(mimeType);
-			let fileData;
-			if (isBinary) fileData = createFileData(content, void 0, "v2", mimeType);
-			else fileData = createFileData(new TextDecoder().decode(content), void 0, this.fileFormat, mimeType);
-			const storeValue = this.convertFileDataToStoreValue(fileData);
-			await store.put(namespace, path, storeValue);
-			responses.push({
-				path,
-				error: null
-			});
+	getNamespaceConfig() {
+		const injectedConfig = getObjectRecord(this.stateAndStore?.config);
+		if (injectedConfig) return {
+			metadata: getObjectRecord(injectedConfig.metadata),
+			configurable: getObjectRecord(injectedConfig.configurable)
+		};
+		try {
+			const configRecord = getObjectRecord(getConfig());
+			if (!configRecord) return;
+			return {
+				metadata: getObjectRecord(configRecord.metadata),
+				configurable: getObjectRecord(configRecord.configurable)
+			};
 		} catch {
-			responses.push({
-				path,
-				error: "invalid_path"
-			});
+			return;
 		}
-		return responses;
 	}
 	/**
-	* Download multiple files.
-	*
-	* @param paths - List of file paths to download
-	* @returns List of FileDownloadResponse objects, one per input path
+	* Legacy assistant-id detection compatible with both Python and the
+	* historical TypeScript `assistantId` runtime property.
 	*/
-	async downloadFiles(paths) {
-		const store = this.getStore();
-		const namespace = this.getNamespace();
-		const responses = [];
-		for (const path of paths) try {
-			const item = await store.get(namespace, path);
-			if (!item) {
-				responses.push({
-					path,
-					content: null,
-					error: "file_not_found"
-				});
-				continue;
-			}
-			const fileDataV2 = migrateToFileDataV2(this.convertStoreItemToFileData(item), path);
-			if (typeof fileDataV2.content === "string") {
-				const content = new TextEncoder().encode(fileDataV2.content);
-				responses.push({
-					path,
-					content,
-					error: null
-				});
-			} else responses.push({
-				path,
-				content: fileDataV2.content,
-				error: null
-			});
-		} catch {
-			responses.push({
-				path,
-				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 literal (fixed-string) search, plus substring fallback
-*   and optional glob include filtering, while preserving virtual path behavior
-*/
-const SUPPORTS_NOFOLLOW = fs$1.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 ? path$1.resolve(rootDir) : process.cwd();
-		this.virtualMode = virtualMode;
-		this.maxFileSizeBytes = maxFileSizeMb * 1024 * 1024;
+	getLegacyAssistantId() {
+		const config = this.getNamespaceConfig();
+		const assistantIdFromConfig = getAssistantIdFromRecord(config?.metadata) ?? getAssistantIdFromRecord(config?.configurable);
+		if (assistantIdFromConfig) return assistantIdFromConfig;
+		const assistantId = this.stateAndStore?.assistantId;
+		return typeof assistantId === "string" && assistantId.length > 0 ? assistantId : void 0;
 	}
 	/**
-	* Resolve a file path with security checks.
+	* Get the namespace for store operations.
 	*
-	* 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.
+	* Resolution order:
+	* 1. Explicit namespace from constructor options
+	* 2. Namespace factory resolved from the current backend context
+	* 3. Assistant ID from runtime config / LangGraph config metadata
+	* 4. Legacy `assistantId` from the injected runtime
+	* 5. `["filesystem"]`
+	*/
+	getNamespace() {
+		if (Array.isArray(this._namespace)) return this._namespace;
+		if (this._namespace) return validateNamespace(this._namespace({
+			state: this.getState(),
+			config: this.getNamespaceConfig(),
+			assistantId: this.getLegacyAssistantId()
+		}));
+		const assistantId = this.getLegacyAssistantId();
+		if (assistantId) return [assistantId, "filesystem"];
+		return ["filesystem"];
+	}
+	/**
+	* Convert a store Item to FileData format.
 	*
-	* @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
+	* @param storeItem - The store Item containing file data
+	* @returns FileData object
+	* @throws Error if required fields are missing or have incorrect types
 	*/
-	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 = path$1.resolve(this.cwd, vpath.substring(1));
-			const relative = path$1.relative(this.cwd, full);
-			if (relative.startsWith("..") || path$1.isAbsolute(relative)) throw new Error(`Path: ${full} outside root directory: ${this.cwd}`);
-			return full;
-		}
-		if (path$1.isAbsolute(key)) return key;
-		return path$1.resolve(this.cwd, key);
+	convertStoreItemToFileData(storeItem) {
+		const value = storeItem.value;
+		if (!(value.content !== void 0 && (Array.isArray(value.content) || typeof value.content === "string" || ArrayBuffer.isView(value.content))) || typeof value.created_at !== "string" || typeof value.modified_at !== "string") throw new Error(`Store item does not contain valid FileData fields. Got keys: ${Object.keys(value).join(", ")}`);
+		return {
+			content: value.content,
+			...value.mimeType ? { mimeType: value.mimeType } : {},
+			created_at: value.created_at,
+			modified_at: value.modified_at
+		};
 	}
 	/**
-	* List files and directories in the specified directory (non-recursive).
+	* Convert FileData to a value suitable for store.put().
 	*
-	* @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.
+	* @param fileData - The FileData to convert
+	* @returns Object with content, mimeType, created_at, and modified_at fields
 	*/
-	async ls(dirPath) {
-		try {
-			const resolvedPath = this.resolvePath(dirPath);
-			if (!(await fs.stat(resolvedPath)).isDirectory()) return { files: [] };
-			const entries = await fs.readdir(resolvedPath, { withFileTypes: true });
-			const results = [];
-			const cwdStr = this.cwd.endsWith(path$1.sep) ? this.cwd : this.cwd + path$1.sep;
-			for (const entry of entries) {
-				const fullPath = path$1.join(resolvedPath, entry.name);
-				try {
-					const entryStat = await fs.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 + path$1.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(path$1.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;
-				}
+	convertFileDataToStoreValue(fileData) {
+		return {
+			content: fileData.content,
+			..."mimeType" in fileData ? { mimeType: fileData.mimeType } : {},
+			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 LsResult with list of FileInfo objects on success or error on failure.
+	*          Directories have a trailing / in their path and is_dir=true.
+	*/
+	async ls(path) {
+		const store = this.getStore();
+		const namespace = this.getNamespace();
+		const items = await this.searchStorePaginated(store, namespace);
+		const infos = [];
+		const subdirs = /* @__PURE__ */ new Set();
+		const normalizedPath = path.endsWith("/") ? path : path + "/";
+		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 = isFileDataV1(fd) ? fd.content.join("\n").length : isFileDataBinary(fd) ? fd.content.byteLength : fd.content.length;
+				infos.push({
+					path: itemKey,
+					is_dir: false,
+					size,
+					modified_at: fd.modified_at
+				});
+			} catch {
+				continue;
 			}
-			results.sort((a, b) => a.path.localeCompare(b.path));
-			return { files: results };
-		} catch {
-			return { files: [] };
 		}
+		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 { files: infos };
 	}
 	/**
-	* Read file content with line numbers.
+	* Read file content.
 	*
-	* @param filePath - Absolute or relative file path
+	* Text files are paginated by line offset/limit.
+	* Binary files return full Uint8Array content (offset/limit ignored).
+	*
+	* @param filePath - Absolute file path
 	* @param offset - Line offset to start reading from (0-indexed)
 	* @param limit - Maximum number of lines to read
-	* @returns Formatted file content with line numbers, or error message
+	* @returns ReadResult with content on success or error on failure
 	*/
 	async read(filePath, offset = 0, limit = 500) {
 		try {
-			const resolvedPath = this.resolvePath(filePath);
-			const mimeType = getMimeType(filePath);
-			const isBinary = !isTextMimeType(mimeType);
-			let content;
-			if (SUPPORTS_NOFOLLOW) {
-				if (!(await fs.stat(resolvedPath)).isFile()) return { error: `File '${filePath}' not found` };
-				const fd = await fs.open(resolvedPath, fs$1.constants.O_RDONLY | fs$1.constants.O_NOFOLLOW);
-				try {
-					if (isBinary) {
-						const buffer = await fd.readFile();
-						return {
-							content: new Uint8Array(buffer),
-							mimeType
-						};
-					}
-					content = await fd.readFile({ encoding: "utf-8" });
-				} finally {
-					await fd.close();
-				}
-			} else {
-				const stat = await fs.lstat(resolvedPath);
-				if (stat.isSymbolicLink()) return { error: `Symlinks are not allowed: ${filePath}` };
-				if (!stat.isFile()) return { error: `File '${filePath}' not found` };
-				if (isBinary) {
-					const buffer = await fs.readFile(resolvedPath);
-					return {
-						content: new Uint8Array(buffer),
-						mimeType
-					};
-				}
-				content = await fs.readFile(resolvedPath, "utf-8");
-			}
-			const emptyMsg = checkEmptyContent(content);
-			if (emptyMsg) return {
-				content: emptyMsg,
-				mimeType
+			const readRawResult = await this.readRaw(filePath);
+			if (readRawResult.error || !readRawResult.data) return { error: readRawResult.error || "File data not found" };
+			const fileDataV2 = migrateToFileDataV2(readRawResult.data, filePath);
+			if (!isTextMimeType(fileDataV2.mimeType)) return {
+				content: fileDataV2.content,
+				mimeType: fileDataV2.mimeType
 			};
-			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)` };
+			if (typeof fileDataV2.content !== "string") return { error: `File '${filePath}' has binary content but text MIME type` };
 			return {
-				content: lines.slice(startIdx, endIdx).join("\n"),
-				mimeType
+				content: fileDataV2.content.split("\n").slice(offset, offset + limit).join("\n"),
+				mimeType: fileDataV2.mimeType
 			};
 		} catch (e) {
-			return { error: `Error reading file '${filePath}': ${e.message}` };
+			return { error: e.message };
 		}
 	}
 	/**
@@ -4761,478 +4917,347 @@ var FilesystemBackend = class {
 	* @returns ReadRawResult with raw file data on success or error on failure
 	*/
 	async readRaw(filePath) {
-		const resolvedPath = this.resolvePath(filePath);
-		const mimeType = getMimeType(filePath);
-		const isBinary = !isTextMimeType(mimeType);
-		let content;
-		let stat;
-		if (SUPPORTS_NOFOLLOW) {
-			stat = await fs.stat(resolvedPath);
-			if (!stat.isFile()) return { error: `File '${filePath}' not found` };
-			const fd = await fs.open(resolvedPath, fs$1.constants.O_RDONLY | fs$1.constants.O_NOFOLLOW);
-			try {
-				if (isBinary) {
-					const buffer = await fd.readFile();
-					return { data: {
-						content: new Uint8Array(buffer),
-						mimeType,
-						created_at: stat.ctime.toISOString(),
-						modified_at: stat.mtime.toISOString()
-					} };
-				}
-				content = await fd.readFile({ encoding: "utf-8" });
-			} finally {
-				await fd.close();
-			}
-		} else {
-			stat = await fs.lstat(resolvedPath);
-			if (stat.isSymbolicLink()) return { error: `Symlinks are not allowed: ${filePath}` };
-			if (!stat.isFile()) return { error: `File '${filePath}' not found` };
-			if (isBinary) {
-				const buffer = await fs.readFile(resolvedPath);
-				return { data: {
-					content: new Uint8Array(buffer),
-					mimeType,
-					created_at: stat.ctime.toISOString(),
-					modified_at: stat.mtime.toISOString()
-				} };
-			}
-			content = await fs.readFile(resolvedPath, "utf-8");
-		}
-		return { data: {
-			content,
-			mimeType,
-			created_at: stat.ctime.toISOString(),
-			modified_at: stat.mtime.toISOString()
-		} };
+		const store = this.getStore();
+		const namespace = this.getNamespace();
+		const item = await store.get(namespace, filePath);
+		if (!item) return { error: `File '${filePath}' not found` };
+		return { data: this.convertStoreItemToFileData(item) };
 	}
 	/**
 	* Create a new file with content.
 	* Returns WriteResult. External storage sets filesUpdate=null.
 	*/
 	async write(filePath, content) {
-		try {
-			const resolvedPath = this.resolvePath(filePath);
-			const isBinary = !isTextMimeType(getMimeType(filePath));
-			try {
-				if ((await fs.lstat(resolvedPath)).isSymbolicLink()) return { error: `Cannot write to ${filePath} because it is a symlink. Symlinks are not allowed.` };
-				return { error: `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.` };
-			} catch {}
-			await fs.mkdir(path$1.dirname(resolvedPath), { recursive: true });
-			if (SUPPORTS_NOFOLLOW) {
-				const flags = fs$1.constants.O_WRONLY | fs$1.constants.O_CREAT | fs$1.constants.O_TRUNC | fs$1.constants.O_NOFOLLOW;
-				const fd = await fs.open(resolvedPath, flags, 420);
-				try {
-					if (isBinary) {
-						const buffer = Buffer.from(content, "base64");
-						await fd.writeFile(buffer);
-					} else await fd.writeFile(content, "utf-8");
-				} finally {
-					await fd.close();
-				}
-			} else if (isBinary) {
-				const buffer = Buffer.from(content, "base64");
-				await fs.writeFile(resolvedPath, buffer);
-			} else await fs.writeFile(resolvedPath, content, "utf-8");
-			return {
-				path: filePath,
-				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 fs.stat(resolvedPath)).isFile()) return { error: `Error: File '${filePath}' not found` };
-				const fd = await fs.open(resolvedPath, fs$1.constants.O_RDONLY | fs$1.constants.O_NOFOLLOW);
-				try {
-					content = await fd.readFile({ encoding: "utf-8" });
-				} finally {
-					await fd.close();
-				}
-			} else {
-				const stat = await fs.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 fs.readFile(resolvedPath, "utf-8");
-			}
-			const result = performStringReplacement(content, oldString, newString, replaceAll);
+		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 mimeType = getMimeType(filePath);
+		const fileData = createFileData(content, void 0, this.fileFormat, mimeType);
+		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;
-			if (SUPPORTS_NOFOLLOW) {
-				const flags = fs$1.constants.O_WRONLY | fs$1.constants.O_TRUNC | fs$1.constants.O_NOFOLLOW;
-				const fd = await fs.open(resolvedPath, flags);
-				try {
-					await fd.writeFile(newContent, "utf-8");
-				} finally {
-					await fd.close();
-				}
-			} else await fs.writeFile(resolvedPath, newContent, "utf-8");
+			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 editing file '${filePath}': ${e.message}` };
-		}
-	}
-	/**
-	* Search for a literal text pattern in files.
-	*
-	* Uses ripgrep if available, falling back to substring search.
-	*
-	* @param pattern - Literal string to search for (NOT regex).
-	* @param dirPath - Directory or file path to search in. Defaults to current directory.
-	* @param glob - Optional glob pattern to filter which files to search.
-	* @returns List of GrepMatch dicts containing path, line number, and matched text.
-	*/
-	async grep(pattern, dirPath = "/", glob = null) {
-		let baseFull;
-		try {
-			baseFull = this.resolvePath(dirPath || ".");
-		} catch {
-			return { matches: [] };
-		}
-		try {
-			await fs.stat(baseFull);
-		} catch {
-			return { matches: [] };
+			return { error: `Error: ${e.message}` };
 		}
-		let results = await this.ripgrepSearch(pattern, baseFull, glob);
-		if (results === null) results = await this.literalSearch(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 };
-	}
-	/**
-	* Search using ripgrep with fixed-string (literal) mode.
-	*
-	* @param pattern - Literal string to search for (unescaped).
-	* @param baseFull - Resolved base path to search in.
-	* @param includeGlob - Optional glob pattern to filter files.
-	* @returns Dict mapping file paths to list of (line_number, line_text) tuples.
-	*          Returns null if ripgrep is unavailable or times out.
-	*/
-	async ripgrepSearch(pattern, baseFull, includeGlob) {
-		return new Promise((resolve) => {
-			const args = ["--json", "-F"];
-			if (includeGlob) args.push("--glob", includeGlob);
-			args.push("--", pattern, baseFull);
-			const proc = 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 = path$1.resolve(ftext);
-							const relative = path$1.relative(this.cwd, resolved);
-							if (relative.startsWith("..")) continue;
-							virtPath = "/" + relative.split(path$1.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 search using literal substring matching when ripgrep is unavailable.
-	*
-	* Recursively searches files, respecting maxFileSizeBytes limit.
-	*
-	* @param pattern - Literal string to search for.
-	* @param baseFull - Resolved base path to search in.
-	* @param includeGlob - Optional glob pattern to filter files by name.
-	* @returns Dict mapping file paths to list of (line_number, line_text) tuples.
+	* Search file contents for a literal text pattern.
+	* Binary files are skipped.
 	*/
-	async literalSearch(pattern, baseFull, includeGlob) {
-		const results = {};
-		const files = await fg("**/*", {
-			cwd: (await fs.stat(baseFull)).isDirectory() ? baseFull : path$1.dirname(baseFull),
-			absolute: true,
-			onlyFiles: true,
-			dot: true
-		});
-		for (const fp of files) try {
-			if (!isTextMimeType(getMimeType(fp))) continue;
-			if (includeGlob && !micromatch.isMatch(path$1.basename(fp), includeGlob)) continue;
-			if ((await fs.stat(fp)).size > this.maxFileSizeBytes) continue;
-			const lines = (await fs.readFile(fp, "utf-8")).split("\n");
-			for (let i = 0; i < lines.length; i++) {
-				const line = lines[i];
-				if (line.includes(pattern)) {
-					let virtPath;
-					if (this.virtualMode) try {
-						const relative = path$1.relative(this.cwd, fp);
-						if (relative.startsWith("..")) continue;
-						virtPath = "/" + relative.split(path$1.sep).join("/");
-					} catch {
-						continue;
-					}
-					else virtPath = fp;
-					if (!results[virtPath]) results[virtPath] = [];
-					results[virtPath].push([i + 1, line]);
-				}
-			}
+	async grep(pattern, path = "/", 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 results;
+		return { matches: grepMatchesFromFiles(files, pattern, path, glob) };
 	}
 	/**
 	* Structured glob matching returning FileInfo objects.
 	*/
-	async glob(pattern, searchPath = "/") {
-		if (pattern.startsWith("/")) pattern = pattern.substring(1);
-		const resolvedSearchPath = searchPath === "/" ? this.cwd : this.resolvePath(searchPath);
-		try {
-			if (!(await fs.stat(resolvedSearchPath)).isDirectory()) return { files: [] };
+	async glob(pattern, path = "/") {
+		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 {
-			return { files: [] };
+			continue;
 		}
-		const results = [];
-		try {
-			const matches = await fg(pattern, {
-				cwd: resolvedSearchPath,
-				absolute: true,
-				onlyFiles: true,
-				dot: true
+		const result = globSearchFiles(files, pattern, path);
+		if (result === "No files found") return { files: [] };
+		const paths = result.split("\n");
+		const infos = [];
+		for (const p of paths) {
+			const fd = files[p];
+			const size = fd ? isFileDataV1(fd) ? fd.content.join("\n").length : isFileDataBinary(fd) ? fd.content.byteLength : fd.content.length : 0;
+			infos.push({
+				path: p,
+				is_dir: false,
+				size,
+				modified_at: fd?.modified_at || ""
 			});
-			for (const matchedPath of matches) try {
-				const stat = await fs.stat(matchedPath);
-				if (!stat.isFile()) continue;
-				const normalizedPath = matchedPath.split("/").join(path$1.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(path$1.sep) ? this.cwd : this.cwd + path$1.sep;
-					let relativePath;
-					if (normalizedPath.startsWith(cwdStr)) relativePath = normalizedPath.substring(cwdStr.length);
-					else if (normalizedPath.startsWith(this.cwd)) relativePath = normalizedPath.substring(this.cwd.length).replace(/^[/\\]/, "");
-					else relativePath = normalizedPath;
-					relativePath = relativePath.split(path$1.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 { files: results };
+		}
+		return { files: infos };
 	}
 	/**
-	* Upload multiple files to the filesystem.
+	* 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 [filePath, content] of files) try {
-			const resolvedPath = this.resolvePath(filePath);
-			await fs.mkdir(path$1.dirname(resolvedPath), { recursive: true });
-			await fs.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"
+		for (const [path, content] of files) try {
+			const mimeType = getMimeType(path);
+			const isBinary = this.fileFormat === "v2" && !isTextMimeType(mimeType);
+			let fileData;
+			if (isBinary) fileData = createFileData(content, void 0, "v2", mimeType);
+			else fileData = createFileData(new TextDecoder().decode(content), void 0, this.fileFormat, mimeType);
+			const storeValue = this.convertFileDataToStoreValue(fileData);
+			await store.put(namespace, path, storeValue);
+			responses.push({
+				path,
+				error: null
 			});
-			else responses.push({
-				path: filePath,
+		} catch {
+			responses.push({
+				path,
 				error: "invalid_path"
 			});
 		}
 		return responses;
 	}
 	/**
-	* Download multiple files from the filesystem.
+	* 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 filePath of paths) try {
-			const resolvedPath = this.resolvePath(filePath);
-			const content = await fs.readFile(resolvedPath);
-			responses.push({
-				path: filePath,
-				content,
+		for (const path of paths) try {
+			const item = await store.get(namespace, path);
+			if (!item) {
+				responses.push({
+					path,
+					content: null,
+					error: "file_not_found"
+				});
+				continue;
+			}
+			const fileDataV2 = migrateToFileDataV2(this.convertStoreItemToFileData(item), path);
+			if (typeof fileDataV2.content === "string") {
+				const content = new TextEncoder().encode(fileDataV2.content);
+				responses.push({
+					path,
+					content,
+					error: null
+				});
+			} else responses.push({
+				path,
+				content: fileDataV2.content,
 				error: null
 			});
-		} catch (e) {
-			if (e.code === "ENOENT") responses.push({
-				path: filePath,
+		} catch {
+			responses.push({
+				path,
 				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
+//#region src/backends/filesystem.ts
 /**
-* Backend that routes file operations to different backends based on path prefix.
+* FilesystemBackend: Read and write files directly from the filesystem.
 *
-* This enables hybrid storage strategies like:
-* - `/memories/` → StoreBackend (persistent, cross-thread)
-* - Everything else → StateBackend (ephemeral, per-thread)
+* 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 literal (fixed-string) search, plus substring fallback
+*   and optional glob include filtering, while preserving virtual path behavior
+*/
+const SUPPORTS_NOFOLLOW = fs$1.constants.O_NOFOLLOW !== void 0;
+/**
+* Backend that reads and writes files directly from the filesystem.
 *
-* The CompositeBackend handles path prefix stripping/re-adding transparently.
+* 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 CompositeBackend = class {
-	default;
-	routes;
-	sortedRoutes;
-	constructor(defaultBackend, routes) {
-		this.default = isSandboxProtocol(defaultBackend) ? adaptSandboxProtocol(defaultBackend) : adaptBackendProtocol(defaultBackend);
-		this.routes = Object.fromEntries(Object.entries(routes).map(([k, v]) => [k, isSandboxProtocol(v) ? adaptSandboxProtocol(v) : adaptBackendProtocol(v)]));
-		this.sortedRoutes = Object.entries(this.routes).sort((a, b) => b[0].length - a[0].length);
-	}
-	/** Delegates to default backend's id if it is a sandbox, otherwise empty string. */
-	get id() {
-		return isSandboxBackend(this.default) ? this.default.id : "";
+var FilesystemBackend = class {
+	cwd;
+	virtualMode;
+	maxFileSizeBytes;
+	constructor(options = {}) {
+		const { rootDir, virtualMode = false, maxFileSizeMb = 10 } = options;
+		this.cwd = rootDir ? path$1.resolve(rootDir) : process.cwd();
+		this.virtualMode = virtualMode;
+		this.maxFileSizeBytes = maxFileSizeMb * 1024 * 1024;
 	}
 	/**
-	* Determine which backend handles this key and strip prefix.
+	* Resolve a file path with security checks.
 	*
-	* @param key - Original file path
-	* @returns Tuple of [backend, stripped_key] where stripped_key has the route
-	*          prefix removed (but keeps leading slash).
+	* 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
 	*/
-	getBackendAndKey(key) {
-		for (const [prefix, backend] of this.sortedRoutes) if (key.startsWith(prefix)) {
-			const suffix = key.substring(prefix.length);
-			return [backend, suffix ? "/" + suffix : "/"];
+	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 = path$1.resolve(this.cwd, vpath.substring(1));
+			const relative = path$1.relative(this.cwd, full);
+			if (relative.startsWith("..") || path$1.isAbsolute(relative)) throw new Error(`Path: ${full} outside root directory: ${this.cwd}`);
+			return full;
 		}
-		return [this.default, key];
+		if (path$1.isAbsolute(key)) return key;
+		return path$1.resolve(this.cwd, key);
 	}
 	/**
 	* List files and directories in the specified directory (non-recursive).
 	*
-	* @param path - Absolute path to directory
-	* @returns LsResult with list of FileInfo objects (with route prefixes added) on success or error on failure.
+	* @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 ls(path) {
-		for (const [routePrefix, backend] of this.sortedRoutes) if (path.startsWith(routePrefix.replace(/\/$/, ""))) {
-			const suffix = path.substring(routePrefix.length);
-			const searchPath = suffix ? "/" + suffix : "/";
-			const result = await backend.ls(searchPath);
-			if (result.error) return result;
-			const prefixed = [];
-			for (const fi of result.files || []) prefixed.push({
-				...fi,
-				path: routePrefix.slice(0, -1) + fi.path
-			});
-			return { files: prefixed };
-		}
-		if (path === "/") {
+	async ls(dirPath) {
+		try {
+			const resolvedPath = this.resolvePath(dirPath);
+			if (!(await fs.stat(resolvedPath)).isDirectory()) return { files: [] };
+			const entries = await fs.readdir(resolvedPath, { withFileTypes: true });
 			const results = [];
-			const defaultResult = await this.default.ls(path);
-			if (defaultResult.error) return defaultResult;
-			results.push(...defaultResult.files || []);
-			for (const [routePrefix] of this.sortedRoutes) results.push({
-				path: routePrefix,
-				is_dir: true,
-				size: 0,
-				modified_at: ""
-			});
+			const cwdStr = this.cwd.endsWith(path$1.sep) ? this.cwd : this.cwd + path$1.sep;
+			for (const entry of entries) {
+				const fullPath = path$1.join(resolvedPath, entry.name);
+				try {
+					const entryStat = await fs.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 + path$1.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(path$1.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 { files: results };
+		} catch {
+			return { files: [] };
+		}
+	}
+	/**
+	* 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 = 500) {
+		try {
+			const resolvedPath = this.resolvePath(filePath);
+			const mimeType = getMimeType(filePath);
+			const isBinary = !isTextMimeType(mimeType);
+			let content;
+			if (SUPPORTS_NOFOLLOW) {
+				if (!(await fs.stat(resolvedPath)).isFile()) return { error: `File '${filePath}' not found` };
+				const fd = await fs.open(resolvedPath, fs$1.constants.O_RDONLY | fs$1.constants.O_NOFOLLOW);
+				try {
+					if (isBinary) {
+						const buffer = await fd.readFile();
+						return {
+							content: new Uint8Array(buffer),
+							mimeType
+						};
+					}
+					content = await fd.readFile({ encoding: "utf-8" });
+				} finally {
+					await fd.close();
+				}
+			} else {
+				const stat = await fs.lstat(resolvedPath);
+				if (stat.isSymbolicLink()) return { error: `Symlinks are not allowed: ${filePath}` };
+				if (!stat.isFile()) return { error: `File '${filePath}' not found` };
+				if (isBinary) {
+					const buffer = await fs.readFile(resolvedPath);
+					return {
+						content: new Uint8Array(buffer),
+						mimeType
+					};
+				}
+				content = await fs.readFile(resolvedPath, "utf-8");
+			}
+			const emptyMsg = checkEmptyContent(content);
+			if (emptyMsg) return {
+				content: emptyMsg,
+				mimeType
+			};
+			const lines = content.split("\n");
+			const startIdx = offset;
+			const endIdx = Math.min(startIdx + limit, lines.length);
+			if (startIdx >= lines.length) return { error: `Line offset ${offset} exceeds file length (${lines.length} lines)` };
+			return {
+				content: lines.slice(startIdx, endIdx).join("\n"),
+				mimeType
+			};
+		} catch (e) {
+			return { error: `Error reading file '${filePath}': ${e.message}` };
 		}
-		return await this.default.ls(path);
-	}
-	/**
-	* 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 = 500) {
-		const [backend, strippedKey] = this.getBackendAndKey(filePath);
-		return await backend.read(strippedKey, offset, limit);
 	}
 	/**
 	* Read file content as raw FileData.
@@ -5241,167 +5266,391 @@ var CompositeBackend = class {
 	* @returns ReadRawResult with raw file data on success or error on failure
 	*/
 	async readRaw(filePath) {
-		const [backend, strippedKey] = this.getBackendAndKey(filePath);
-		return await backend.readRaw(strippedKey);
+		const resolvedPath = this.resolvePath(filePath);
+		const mimeType = getMimeType(filePath);
+		const isBinary = !isTextMimeType(mimeType);
+		let content;
+		let stat;
+		if (SUPPORTS_NOFOLLOW) {
+			stat = await fs.stat(resolvedPath);
+			if (!stat.isFile()) return { error: `File '${filePath}' not found` };
+			const fd = await fs.open(resolvedPath, fs$1.constants.O_RDONLY | fs$1.constants.O_NOFOLLOW);
+			try {
+				if (isBinary) {
+					const buffer = await fd.readFile();
+					return { data: {
+						content: new Uint8Array(buffer),
+						mimeType,
+						created_at: stat.ctime.toISOString(),
+						modified_at: stat.mtime.toISOString()
+					} };
+				}
+				content = await fd.readFile({ encoding: "utf-8" });
+			} finally {
+				await fd.close();
+			}
+		} else {
+			stat = await fs.lstat(resolvedPath);
+			if (stat.isSymbolicLink()) return { error: `Symlinks are not allowed: ${filePath}` };
+			if (!stat.isFile()) return { error: `File '${filePath}' not found` };
+			if (isBinary) {
+				const buffer = await fs.readFile(resolvedPath);
+				return { data: {
+					content: new Uint8Array(buffer),
+					mimeType,
+					created_at: stat.ctime.toISOString(),
+					modified_at: stat.mtime.toISOString()
+				} };
+			}
+			content = await fs.readFile(resolvedPath, "utf-8");
+		}
+		return { data: {
+			content,
+			mimeType,
+			created_at: stat.ctime.toISOString(),
+			modified_at: stat.mtime.toISOString()
+		} };
 	}
 	/**
-	* Structured search results or error string for invalid input.
+	* Create a new file with content.
+	* Returns WriteResult. External storage sets filesUpdate=null.
 	*/
-	async grep(pattern, path = "/", glob = null) {
-		for (const [routePrefix, backend] of this.sortedRoutes) if (path.startsWith(routePrefix.replace(/\/$/, ""))) {
-			const searchPath = path.substring(routePrefix.length - 1);
-			const raw = await backend.grep(pattern, searchPath || "/", glob);
-			if (raw.error) return raw;
-			return { matches: (raw.matches || []).map((m) => ({
-				...m,
-				path: routePrefix.slice(0, -1) + m.path
-			})) };
+	async write(filePath, content) {
+		try {
+			const resolvedPath = this.resolvePath(filePath);
+			const isBinary = !isTextMimeType(getMimeType(filePath));
+			try {
+				if ((await fs.lstat(resolvedPath)).isSymbolicLink()) return { error: `Cannot write to ${filePath} because it is a symlink. Symlinks are not allowed.` };
+				return { error: `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.` };
+			} catch {}
+			await fs.mkdir(path$1.dirname(resolvedPath), { recursive: true });
+			if (SUPPORTS_NOFOLLOW) {
+				const flags = fs$1.constants.O_WRONLY | fs$1.constants.O_CREAT | fs$1.constants.O_TRUNC | fs$1.constants.O_NOFOLLOW;
+				const fd = await fs.open(resolvedPath, flags, 420);
+				try {
+					if (isBinary) {
+						const buffer = Buffer.from(content, "base64");
+						await fd.writeFile(buffer);
+					} else await fd.writeFile(content, "utf-8");
+				} finally {
+					await fd.close();
+				}
+			} else if (isBinary) {
+				const buffer = Buffer.from(content, "base64");
+				await fs.writeFile(resolvedPath, buffer);
+			} else await fs.writeFile(resolvedPath, content, "utf-8");
+			return {
+				path: filePath,
+				filesUpdate: null
+			};
+		} catch (e) {
+			return { error: `Error writing file '${filePath}': ${e.message}` };
 		}
-		const allMatches = [];
-		const rawDefault = await this.default.grep(pattern, path, glob);
-		if (rawDefault.error) return rawDefault;
-		allMatches.push(...rawDefault.matches || []);
-		for (const [routePrefix, backend] of Object.entries(this.routes)) {
-			const raw = await backend.grep(pattern, "/", glob);
-			if (raw.error) return raw;
-			const matches = (raw.matches || []).map((m) => ({
-				...m,
-				path: routePrefix.slice(0, -1) + m.path
-			}));
-			allMatches.push(...matches);
+	}
+	/**
+	* 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 fs.stat(resolvedPath)).isFile()) return { error: `Error: File '${filePath}' not found` };
+				const fd = await fs.open(resolvedPath, fs$1.constants.O_RDONLY | fs$1.constants.O_NOFOLLOW);
+				try {
+					content = await fd.readFile({ encoding: "utf-8" });
+				} finally {
+					await fd.close();
+				}
+			} else {
+				const stat = await fs.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 fs.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 = fs$1.constants.O_WRONLY | fs$1.constants.O_TRUNC | fs$1.constants.O_NOFOLLOW;
+				const fd = await fs.open(resolvedPath, flags);
+				try {
+					await fd.writeFile(newContent, "utf-8");
+				} finally {
+					await fd.close();
+				}
+			} else await fs.writeFile(resolvedPath, newContent, "utf-8");
+			return {
+				path: filePath,
+				filesUpdate: null,
+				occurrences
+			};
+		} catch (e) {
+			return { error: `Error editing file '${filePath}': ${e.message}` };
 		}
-		return { matches: allMatches };
 	}
 	/**
-	* Structured glob matching returning FileInfo objects.
+	* Search for a literal text pattern in files.
+	*
+	* Uses ripgrep if available, falling back to substring search.
+	*
+	* @param pattern - Literal string to search for (NOT regex).
+	* @param dirPath - Directory or file path to search in. Defaults to current directory.
+	* @param glob - Optional glob pattern to filter which files to search.
+	* @returns List of GrepMatch dicts containing path, line number, and matched text.
 	*/
-	async glob(pattern, path = "/") {
-		const results = [];
-		for (const [routePrefix, backend] of this.sortedRoutes) if (path.startsWith(routePrefix.replace(/\/$/, ""))) {
-			const searchPath = path.substring(routePrefix.length - 1);
-			const result = await backend.glob(pattern, searchPath || "/");
-			if (result.error) return result;
-			return { files: (result.files || []).map((fi) => ({
-				...fi,
-				path: routePrefix.slice(0, -1) + fi.path
-			})) };
+	async grep(pattern, dirPath = "/", glob = null) {
+		let baseFull;
+		try {
+			baseFull = this.resolvePath(dirPath || ".");
+		} catch {
+			return { matches: [] };
 		}
-		const defaultResult = await this.default.glob(pattern, path);
-		if (defaultResult.error) return defaultResult;
-		results.push(...defaultResult.files || []);
-		for (const [routePrefix, backend] of Object.entries(this.routes)) {
-			const result = await backend.glob(pattern, "/");
-			if (result.error) continue;
-			const files = (result.files || []).map((fi) => ({
-				...fi,
-				path: routePrefix.slice(0, -1) + fi.path
-			}));
-			results.push(...files);
+		try {
+			await fs.stat(baseFull);
+		} catch {
+			return { matches: [] };
 		}
-		results.sort((a, b) => a.path.localeCompare(b.path));
-		return { files: results };
+		let results = await this.ripgrepSearch(pattern, baseFull, glob);
+		if (results === null) results = await this.literalSearch(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 };
+	}
+	/**
+	* Search using ripgrep with fixed-string (literal) mode.
+	*
+	* @param pattern - Literal string to search for (unescaped).
+	* @param baseFull - Resolved base path to search in.
+	* @param includeGlob - Optional glob pattern to filter files.
+	* @returns Dict mapping file paths to list of (line_number, line_text) tuples.
+	*          Returns null if ripgrep is unavailable or times out.
+	*/
+	async ripgrepSearch(pattern, baseFull, includeGlob) {
+		return new Promise((resolve) => {
+			const args = ["--json", "-F"];
+			if (includeGlob) args.push("--glob", includeGlob);
+			args.push("--", pattern, baseFull);
+			const proc = 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 = path$1.resolve(ftext);
+							const relative = path$1.relative(this.cwd, resolved);
+							if (relative.startsWith("..")) continue;
+							virtPath = "/" + relative.split(path$1.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);
+			});
+		});
 	}
 	/**
-	* Create a new file, routing to appropriate backend.
+	* Fallback search using literal substring matching when ripgrep is unavailable.
 	*
-	* @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.
+	* Recursively searches files, respecting maxFileSizeBytes limit.
 	*
-	* @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
+	* @param pattern - Literal string to search for.
+	* @param baseFull - Resolved base path to search in.
+	* @param includeGlob - Optional glob pattern to filter files by name.
+	* @returns Dict mapping file paths to list of (line_number, line_text) tuples.
 	*/
-	async edit(filePath, oldString, newString, replaceAll = false) {
-		const [backend, strippedKey] = this.getBackendAndKey(filePath);
-		return await backend.edit(strippedKey, oldString, newString, replaceAll);
+	async literalSearch(pattern, baseFull, includeGlob) {
+		const results = {};
+		const files = await fg("**/*", {
+			cwd: (await fs.stat(baseFull)).isDirectory() ? baseFull : path$1.dirname(baseFull),
+			absolute: true,
+			onlyFiles: true,
+			dot: true
+		});
+		for (const fp of files) try {
+			if (!isTextMimeType(getMimeType(fp))) continue;
+			if (includeGlob && !micromatch.isMatch(path$1.basename(fp), includeGlob)) continue;
+			if ((await fs.stat(fp)).size > this.maxFileSizeBytes) continue;
+			const lines = (await fs.readFile(fp, "utf-8")).split("\n");
+			for (let i = 0; i < lines.length; i++) {
+				const line = lines[i];
+				if (line.includes(pattern)) {
+					let virtPath;
+					if (this.virtualMode) try {
+						const relative = path$1.relative(this.cwd, fp);
+						if (relative.startsWith("..")) continue;
+						virtPath = "/" + relative.split(path$1.sep).join("/");
+					} catch {
+						continue;
+					}
+					else virtPath = fp;
+					if (!results[virtPath]) results[virtPath] = [];
+					results[virtPath].push([i + 1, line]);
+				}
+			}
+		} catch {
+			continue;
+		}
+		return results;
 	}
 	/**
-	* 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
+	* Structured glob matching returning FileInfo objects.
 	*/
-	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));
+	async glob(pattern, searchPath = "/") {
+		if (pattern.startsWith("/")) pattern = pattern.substring(1);
+		const resolvedSearchPath = searchPath === "/" ? this.cwd : this.resolvePath(searchPath);
+		try {
+			if (!(await fs.stat(resolvedSearchPath)).isDirectory()) return { files: [] };
+		} catch {
+			return { files: [] };
+		}
+		const results = [];
+		try {
+			const matches = await fg(pattern, {
+				cwd: resolvedSearchPath,
+				absolute: true,
+				onlyFiles: true,
+				dot: true
+			});
+			for (const matchedPath of matches) try {
+				const stat = await fs.stat(matchedPath);
+				if (!stat.isFile()) continue;
+				const normalizedPath = matchedPath.split("/").join(path$1.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(path$1.sep) ? this.cwd : this.cwd + path$1.sep;
+					let relativePath;
+					if (normalizedPath.startsWith(cwdStr)) relativePath = normalizedPath.substring(cwdStr.length);
+					else if (normalizedPath.startsWith(this.cwd)) relativePath = normalizedPath.substring(this.cwd.length).replace(/^[/\\]/, "");
+					else relativePath = normalizedPath;
+					relativePath = relativePath.split(path$1.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 { files: results };
 	}
 	/**
-	* Upload multiple files, batching by backend for efficiency.
+	* 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 results = Array.from({ length: files.length }, () => null);
-		const batchesByBackend = /* @__PURE__ */ new Map();
-		for (let idx = 0; idx < files.length; idx++) {
-			const [path, content] = files[idx];
-			const [backend, strippedPath] = this.getBackendAndKey(path);
-			if (!batchesByBackend.has(backend)) batchesByBackend.set(backend, []);
-			batchesByBackend.get(backend).push({
-				idx,
-				path: strippedPath,
-				content
+		const responses = [];
+		for (const [filePath, content] of files) try {
+			const resolvedPath = this.resolvePath(filePath);
+			await fs.mkdir(path$1.dirname(resolvedPath), { recursive: true });
+			await fs.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"
 			});
 		}
-		for (const [backend, batch] of batchesByBackend) {
-			if (!backend.uploadFiles) throw new Error("Backend does not support uploadFiles");
-			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;
+		return responses;
 	}
 	/**
-	* Download multiple files, batching by backend for efficiency.
+	* 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 results = Array.from({ length: paths.length }, () => null);
-		const batchesByBackend = /* @__PURE__ */ new Map();
-		for (let idx = 0; idx < paths.length; idx++) {
-			const path = paths[idx];
-			const [backend, strippedPath] = this.getBackendAndKey(path);
-			if (!batchesByBackend.has(backend)) batchesByBackend.set(backend, []);
-			batchesByBackend.get(backend).push({
-				idx,
-				path: strippedPath
+		const responses = [];
+		for (const filePath of paths) try {
+			const resolvedPath = this.resolvePath(filePath);
+			const content = await fs.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"
 			});
 		}
-		for (const [backend, batch] of batchesByBackend) {
-			if (!backend.downloadFiles) throw new Error("Backend does not support downloadFiles");
-			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;
+		return responses;
 	}
 };
 //#endregion
@@ -5814,7 +6063,7 @@ const STAT_C_SCRIPT = "for f; do if [ -d \"$f\" ]; then t=d; elif [ -L \"$f\" ];
 */
 function buildLsCommand(dirPath) {
 	const quotedPath = shellQuote(dirPath);
-	const findBase = `find ${quotedPath} -maxdepth 1 -not -path ${quotedPath}`;
+	const findBase = `find -L ${quotedPath} -maxdepth 1 -not -path ${quotedPath}`;
 	return `if find /dev/null -maxdepth 0 -printf '' 2>/dev/null; then ${findBase} -printf '%s\\t%T@\\t%y\\t%p\\n' 2>/dev/null; elif stat -c %s /dev/null >/dev/null 2>&1; then ${findBase} -exec sh -c '${STAT_C_SCRIPT}' _ {} +; else ${findBase} -exec stat -f '%z\t%m\t%Sp\t%N' {} + 2>/dev/null; fi || true`;
 }
 /**
@@ -5825,7 +6074,7 @@ function buildLsCommand(dirPath) {
 */
 function buildFindCommand(searchPath) {
 	const quotedPath = shellQuote(searchPath);
-	const findBase = `find ${quotedPath} -not -path ${quotedPath}`;
+	const findBase = `find -L ${quotedPath} -not -path ${quotedPath}`;
 	return `if find /dev/null -maxdepth 0 -printf '' 2>/dev/null; then ${findBase} -printf '%s\\t%T@\\t%y\\t%p\\n' 2>/dev/null; elif stat -c %s /dev/null >/dev/null 2>&1; then ${findBase} -exec sh -c '${STAT_C_SCRIPT}' _ {} +; else ${findBase} -exec stat -f '%z\t%m\t%Sp\t%N' {} + 2>/dev/null; fi || true`;
 }
 /**
@@ -5858,7 +6107,7 @@ function buildReadCommand(filePath, offset, limit) {
 function buildGrepCommand(pattern, searchPath, globPattern) {
 	const patternEscaped = shellQuote(pattern);
 	const searchPathQuoted = shellQuote(searchPath);
-	if (globPattern) return `find ${searchPathQuoted} -type f -name ${shellQuote(globPattern)} -exec grep -HnF -e ${patternEscaped} {} + 2>/dev/null || true`;
+	if (globPattern) return `find -L ${searchPathQuoted} -type f -name ${shellQuote(globPattern)} -exec grep -HnF -e ${patternEscaped} {} + 2>/dev/null || true`;
 	return `grep -rHnF -e ${patternEscaped} ${searchPathQuoted} 2>/dev/null || true`;
 }
 /**
@@ -6153,6 +6402,8 @@ var BaseSandbox = class {
 *   await sandbox.close();
 * }
 * ```
+*
+* @module
 */
 /**
 * LangSmith Sandbox backend for deepagents.
@@ -6162,6 +6413,8 @@ var BaseSandbox = class {
 *
 * Use the static `LangSmithSandbox.create()` factory for the simplest setup,
 * or construct directly with an existing `Sandbox` instance.
+*
+* @experimental This feature is experimental, and breaking changes are expected.
 */
 var LangSmithSandbox = class LangSmithSandbox extends BaseSandbox {
 	#sandbox;
@@ -6454,7 +6707,7 @@ function isAnthropicModel(model) {
 * ```
 */
 function createDeepAgent(params = {}) {
-	const { model = new ChatAnthropic("claude-sonnet-4-6"), tools = [], systemPrompt, middleware: customMiddleware = [], subagents = [], responseFormat, contextSchema, checkpointer, store, backend = (config) => new StateBackend(config), interruptOn, name, memory, skills } = params;
+	const { model = "anthropic:claude-sonnet-4-6", tools = [], systemPrompt, middleware: customMiddleware = [], subagents = [], responseFormat, contextSchema, checkpointer, store, backend = (config) => new StateBackend(config), interruptOn, name, memory, skills, permissions = [] } = params;
 	const collidingTools = tools.map((t) => t.name).filter((n) => typeof n === "string" && BUILTIN_TOOL_NAMES.has(n));
 	if (collidingTools.length > 0) throw new ConfigurationError(`Tool name(s) [${collidingTools.join(", ")}] conflict with built-in tools. Rename your custom tools to avoid this.`, "TOOL_NAME_COLLISION");
 	const anthropicModel = isAnthropicModel(model);
@@ -6470,13 +6723,14 @@ function createDeepAgent(params = {}) {
 	* If a custom subagent needs skills, it must specify its own `skills` array.
 	*/
 	const normalizeSubagentSpec = (input) => {
+		const effectivePermissions = input.permissions ?? permissions;
 		const subagentMiddleware = [
 			todoListMiddleware(),
-			createFilesystemMiddleware({ backend }),
-			createSummarizationMiddleware({
+			createFilesystemMiddleware({
 				backend,
-				model
+				permissions: effectivePermissions
 			}),
+			createSummarizationMiddleware({ backend }),
 			createPatchToolCallsMiddleware(),
 			...input.skills != null && input.skills.length > 0 ? [createSkillsMiddleware({
 				backend,
@@ -6509,7 +6763,10 @@ function createDeepAgent(params = {}) {
 	})] : [];
 	const [todoMiddleware, fsMiddleware, subagentMiddleware, summarizationMiddleware, patchToolCallsMiddleware] = [
 		todoListMiddleware(),
-		createFilesystemMiddleware({ backend }),
+		createFilesystemMiddleware({
+			backend,
+			permissions
+		}),
 		createSubAgentMiddleware({
 			defaultModel: model,
 			defaultTools: tools,
@@ -6517,10 +6774,7 @@ function createDeepAgent(params = {}) {
 			subagents: inlineSubagents,
 			generalPurposeAgent: false
 		}),
-		createSummarizationMiddleware({
-			model,
-			backend
-		}),
+		createSummarizationMiddleware({ backend }),
 		createPatchToolCallsMiddleware()
 	];
 	const middleware = [