deepagents 1.3.0 → 1.4.0

package/dist/index.js

@@ -1,17 +1,39 @@
 import { AIMessage, ToolMessage, anthropicPromptCachingMiddleware, createAgent, createMiddleware, humanInTheLoopMiddleware, summarizationMiddleware, todoListMiddleware, tool } from "langchain";
 import { Command, REMOVE_ALL_MESSAGES, getCurrentTaskInput, isCommand } from "@langchain/langgraph";
-import { z } from "zod/v3";
-import { withLangGraph } from "@langchain/langgraph/zod";
+import { z } from "zod/v4";
 import micromatch from "micromatch";
-import * as path from "path";
 import { basename } from "path";
+import { z as z$1 } from "zod/v3";
 import { HumanMessage, RemoveMessage } from "@langchain/core/messages";
-import * as fs from "fs/promises";
-import * as fsSync from "fs";
-import { spawn } from "child_process";
+import fs from "node:fs/promises";
+import fs$1 from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
 import fg from "fast-glob";
+import os from "node:os";
+import { z as z$2 } from "zod";
+import yaml from "yaml";
 
+//#region src/backends/protocol.ts
+/**
+* Type guard to check if a backend supports execution.
+*
+* @param backend - Backend instance to check
+* @returns True if the backend implements SandboxBackendProtocol
+*/
+function isSandboxBackend(backend) {
+	return typeof backend.execute === "function" && typeof backend.id === "string";
+}
+
+//#endregion
 //#region src/backends/utils.ts
+/**
+* Shared utility functions for memory backend implementations.
+*
+* This module contains both user-facing string formatters and structured
+* helpers used by backends and the composite router. Structured helpers
+* enable composition without fragile string parsing.
+*/
 const EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents";
 const MAX_LINE_LENGTH = 1e4;
 const LINE_NUMBER_WIDTH = 6;
@@ -378,11 +400,75 @@ var StateBackend = class {
 		}
 		return infos;
 	}
+	/**
+	* Upload multiple files.
+	*
+	* Note: Since LangGraph state must be updated via Command objects,
+	* the caller must apply filesUpdate via Command after calling this method.
+	*
+	* @param files - List of [path, content] tuples to upload
+	* @returns List of FileUploadResponse objects, one per input file
+	*/
+	uploadFiles(files) {
+		const responses = [];
+		const updates = {};
+		for (const [path$1, content] of files) try {
+			updates[path$1] = createFileData(new TextDecoder().decode(content));
+			responses.push({
+				path: path$1,
+				error: null
+			});
+		} catch {
+			responses.push({
+				path: path$1,
+				error: "invalid_path"
+			});
+		}
+		const result = responses;
+		result.filesUpdate = updates;
+		return result;
+	}
+	/**
+	* Download multiple files.
+	*
+	* @param paths - List of file paths to download
+	* @returns List of FileDownloadResponse objects, one per input path
+	*/
+	downloadFiles(paths) {
+		const files = this.getFiles();
+		const responses = [];
+		for (const path$1 of paths) {
+			const fileData = files[path$1];
+			if (!fileData) {
+				responses.push({
+					path: path$1,
+					content: null,
+					error: "file_not_found"
+				});
+				continue;
+			}
+			const contentStr = fileDataToString(fileData);
+			const content = new TextEncoder().encode(contentStr);
+			responses.push({
+				path: path$1,
+				content,
+				error: null
+			});
+		}
+		return responses;
+	}
 };
 
 //#endregion
 //#region src/middleware/fs.ts
 /**
+* Middleware for providing filesystem tools to an agent.
+*
+* Provides ls, read_file, write_file, edit_file, glob, and grep tools with support for:
+* - Pluggable backends (StateBackend, StoreBackend, FilesystemBackend, CompositeBackend)
+* - Tool result eviction for large outputs
+*/
+/**
 * Zod v3 schema for FileData (re-export from backends)
 */
 const FileDataSchema = z.object({
@@ -405,6 +491,16 @@ function fileDataReducer(left, right) {
 	return result;
 }
 /**
+* Shared filesystem state schema.
+* Defined at module level to ensure the same object identity is used across all agents,
+* preventing "Channel already exists with different type" errors when multiple agents
+* use createFilesystemMiddleware.
+*/
+const FilesystemStateSchema = z.object({ files: z.record(z.string(), FileDataSchema).default({}).meta({ reducer: {
+	fn: fileDataReducer,
+	schema: z.record(z.string(), FileDataSchema.nullable())
+} }) });
+/**
 * Resolve backend from factory or instance.
 *
 * @param backend - Backend instance or factory function
@@ -428,6 +524,31 @@ const WRITE_FILE_TOOL_DESCRIPTION = "Write content to a new file. Returns an err
 const EDIT_FILE_TOOL_DESCRIPTION = "Edit a file by replacing a specific string with a new string";
 const GLOB_TOOL_DESCRIPTION = "Find files matching a glob pattern (e.g., '**/*.py' for all Python files)";
 const GREP_TOOL_DESCRIPTION = "Search for a regex pattern in files. Returns matching files and line numbers";
+const EXECUTE_TOOL_DESCRIPTION = `Executes a given command in the sandbox environment with proper handling and security measures.
+
+Before executing the command, please follow these steps:
+
+1. Directory Verification:
+   - If the command will create new directories or files, first use the ls tool to verify the parent directory exists
+
+2. Command Execution:
+   - Always quote file paths that contain spaces with double quotes
+   - Commands run in an isolated sandbox environment
+   - Returns combined stdout/stderr output with exit code
+
+Usage notes:
+  - The command parameter is required
+  - If the output is very large, it may be truncated
+  - IMPORTANT: Avoid using search commands like find and grep. Use the grep, glob tools instead.
+  - Avoid read tools like cat, head, tail - use read_file instead.
+  - Use '&&' to chain dependent commands, ';' for independent commands
+  - Try to use absolute paths to avoid cd`;
+const EXECUTION_SYSTEM_PROMPT = `## Execute Tool \`execute\`
+
+You have access to an \`execute\` tool for running shell commands in a sandboxed environment.
+Use this tool to run commands, scripts, tests, builds, and other shell operations.
+
+- execute: run a shell command in the sandbox (returns output and exit code)`;
 /**
 * Create ls tool using backend.
 */
@@ -471,8 +592,8 @@ function createReadFileTool(backend, options) {
 		description: customDescription || READ_FILE_TOOL_DESCRIPTION,
 		schema: z.object({
 			file_path: z.string().describe("Absolute path to the file to read"),
-			offset: z.number({ coerce: true }).optional().default(0).describe("Line offset to start reading from (0-indexed)"),
-			limit: z.number({ coerce: true }).optional().default(2e3).describe("Maximum number of lines to read")
+			offset: z.coerce.number().optional().default(0).describe("Line offset to start reading from (0-indexed)"),
+			limit: z.coerce.number().optional().default(2e3).describe("Maximum number of lines to read")
 		})
 	});
 }
@@ -602,35 +723,66 @@ function createGrepTool(backend, options) {
 	});
 }
 /**
+* Create execute tool using backend.
+*/
+function createExecuteTool(backend, options) {
+	const { customDescription } = options;
+	return tool(async (input, config) => {
+		const resolvedBackend = getBackend(backend, {
+			state: getCurrentTaskInput(config),
+			store: config.store
+		});
+		if (!isSandboxBackend(resolvedBackend)) return "Error: Execution not available. This agent's backend does not support command execution (SandboxBackendProtocol). To use the execute tool, provide a backend that implements SandboxBackendProtocol.";
+		const result = await resolvedBackend.execute(input.command);
+		const parts = [result.output];
+		if (result.exitCode !== null) {
+			const status = result.exitCode === 0 ? "succeeded" : "failed";
+			parts.push(`\n[Command ${status} with exit code ${result.exitCode}]`);
+		}
+		if (result.truncated) parts.push("\n[Output was truncated due to size limits]");
+		return parts.join("");
+	}, {
+		name: "execute",
+		description: customDescription || EXECUTE_TOOL_DESCRIPTION,
+		schema: z.object({ command: z.string().describe("The shell command to execute") })
+	});
+}
+/**
 * Create filesystem middleware with all tools and features.
 */
 function createFilesystemMiddleware(options = {}) {
 	const { backend = (stateAndStore) => new StateBackend(stateAndStore), systemPrompt: customSystemPrompt = null, customToolDescriptions = null, toolTokenLimitBeforeEvict = 2e4 } = options;
-	const systemPrompt = customSystemPrompt || FILESYSTEM_SYSTEM_PROMPT;
-	const tools = [
-		createLsTool(backend, { customDescription: customToolDescriptions?.ls }),
-		createReadFileTool(backend, { customDescription: customToolDescriptions?.read_file }),
-		createWriteFileTool(backend, { customDescription: customToolDescriptions?.write_file }),
-		createEditFileTool(backend, { customDescription: customToolDescriptions?.edit_file }),
-		createGlobTool(backend, { customDescription: customToolDescriptions?.glob }),
-		createGrepTool(backend, { customDescription: customToolDescriptions?.grep })
-	];
+	const baseSystemPrompt = customSystemPrompt || FILESYSTEM_SYSTEM_PROMPT;
 	return createMiddleware({
 		name: "FilesystemMiddleware",
-		stateSchema: z.object({ files: withLangGraph(z.record(z.string(), FileDataSchema).default({}), { reducer: {
-			fn: fileDataReducer,
-			schema: z.record(z.string(), FileDataSchema.nullable())
-		} }) }),
-		tools,
-		wrapModelCall: systemPrompt ? async (request, handler) => {
+		stateSchema: FilesystemStateSchema,
+		tools: [
+			createLsTool(backend, { customDescription: customToolDescriptions?.ls }),
+			createReadFileTool(backend, { customDescription: customToolDescriptions?.read_file }),
+			createWriteFileTool(backend, { customDescription: customToolDescriptions?.write_file }),
+			createEditFileTool(backend, { customDescription: customToolDescriptions?.edit_file }),
+			createGlobTool(backend, { customDescription: customToolDescriptions?.glob }),
+			createGrepTool(backend, { customDescription: customToolDescriptions?.grep }),
+			createExecuteTool(backend, { customDescription: customToolDescriptions?.execute })
+		],
+		wrapModelCall: async (request, handler) => {
+			const supportsExecution = isSandboxBackend(getBackend(backend, {
+				state: request.state || {},
+				store: request.config?.store
+			}));
+			let tools = request.tools;
+			if (!supportsExecution) tools = tools.filter((t) => t.name !== "execute");
+			let systemPrompt = baseSystemPrompt;
+			if (supportsExecution) systemPrompt = `${systemPrompt}\n\n${EXECUTION_SYSTEM_PROMPT}`;
 			const currentSystemPrompt = request.systemPrompt || "";
 			const newSystemPrompt = currentSystemPrompt ? `${currentSystemPrompt}\n\n${systemPrompt}` : systemPrompt;
 			return handler({
 				...request,
+				tools,
 				systemPrompt: newSystemPrompt
 			});
-		} : void 0,
-		wrapToolCall: toolTokenLimitBeforeEvict ? (async (request, handler) => {
+		},
+		wrapToolCall: toolTokenLimitBeforeEvict ? async (request, handler) => {
 			const result = await handler(request);
 			async function processToolMessage(msg) {
 				if (typeof msg.content === "string" && msg.content.length > toolTokenLimitBeforeEvict * 4) {
@@ -687,7 +839,7 @@ function createFilesystemMiddleware(options = {}) {
 				} });
 			}
 			return result;
-		}) : void 0
+		} : void 0
 	});
 }
 
@@ -697,7 +849,8 @@ const DEFAULT_SUBAGENT_PROMPT = "In order to complete the objective that the use
 const EXCLUDED_STATE_KEYS = [
 	"messages",
 	"todos",
-	"jumpTo"
+	"jumpTo",
+	"files"
 ];
 const DEFAULT_GENERAL_PURPOSE_DESCRIPTION = "General-purpose agent for researching complex questions, searching for files and content, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. This agent has access to all tools as the main agent.";
 function getTaskToolDescription(subagentDescriptions) {
@@ -931,9 +1084,9 @@ function createTaskTool(options) {
 	}, {
 		name: "task",
 		description: taskDescription ? taskDescription : getTaskToolDescription(subagentDescriptions),
-		schema: z.object({
-			description: z.string().describe("The task to execute with the selected agent"),
-			subagent_type: z.string().describe(`Name of the agent to use. Available: ${Object.keys(subagentGraphs).join(", ")}`)
+		schema: z$1.object({
+			description: z$1.string().describe("The task to execute with the selected agent"),
+			subagent_type: z$1.string().describe(`Name of the agent to use. Available: ${Object.keys(subagentGraphs).join(", ")}`)
 		})
 	});
 }
@@ -1268,11 +1421,82 @@ var StoreBackend = class {
 		}
 		return infos;
 	}
+	/**
+	* Upload multiple files.
+	*
+	* @param files - List of [path, content] tuples to upload
+	* @returns List of FileUploadResponse objects, one per input file
+	*/
+	async uploadFiles(files) {
+		const store = this.getStore();
+		const namespace = this.getNamespace();
+		const responses = [];
+		for (const [path$1, content] of files) try {
+			const fileData = createFileData(new TextDecoder().decode(content));
+			const storeValue = this.convertFileDataToStoreValue(fileData);
+			await store.put(namespace, path$1, storeValue);
+			responses.push({
+				path: path$1,
+				error: null
+			});
+		} catch {
+			responses.push({
+				path: path$1,
+				error: "invalid_path"
+			});
+		}
+		return responses;
+	}
+	/**
+	* Download multiple files.
+	*
+	* @param paths - List of file paths to download
+	* @returns List of FileDownloadResponse objects, one per input path
+	*/
+	async downloadFiles(paths) {
+		const store = this.getStore();
+		const namespace = this.getNamespace();
+		const responses = [];
+		for (const path$1 of paths) try {
+			const item = await store.get(namespace, path$1);
+			if (!item) {
+				responses.push({
+					path: path$1,
+					content: null,
+					error: "file_not_found"
+				});
+				continue;
+			}
+			const contentStr = fileDataToString(this.convertStoreItemToFileData(item));
+			const content = new TextEncoder().encode(contentStr);
+			responses.push({
+				path: path$1,
+				content,
+				error: null
+			});
+		} catch {
+			responses.push({
+				path: path$1,
+				content: null,
+				error: "file_not_found"
+			});
+		}
+		return responses;
+	}
 };
 
 //#endregion
 //#region src/backends/filesystem.ts
-const SUPPORTS_NOFOLLOW = fsSync.constants.O_NOFOLLOW !== void 0;
+/**
+* FilesystemBackend: Read and write files directly from the filesystem.
+*
+* Security and search upgrades:
+* - Secure path resolution with root containment when in virtual_mode (sandboxed to cwd)
+* - Prevent symlink-following on file I/O using O_NOFOLLOW when available
+* - Ripgrep-powered grep with JSON parsing, plus regex fallback
+*   and optional glob include filtering, while preserving virtual path behavior
+*/
+const SUPPORTS_NOFOLLOW = fs$1.constants.O_NOFOLLOW !== void 0;
 /**
 * Backend that reads and writes files directly from the filesystem.
 *
@@ -1391,7 +1615,7 @@ var FilesystemBackend = class {
 			let content;
 			if (SUPPORTS_NOFOLLOW) {
 				if (!(await fs.stat(resolvedPath)).isFile()) return `Error: File '${filePath}' not found`;
-				const fd = await fs.open(resolvedPath, fsSync.constants.O_RDONLY | fsSync.constants.O_NOFOLLOW);
+				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 {
@@ -1427,7 +1651,7 @@ var FilesystemBackend = class {
 		if (SUPPORTS_NOFOLLOW) {
 			stat = await fs.stat(resolvedPath);
 			if (!stat.isFile()) throw new Error(`File '${filePath}' not found`);
-			const fd = await fs.open(resolvedPath, fsSync.constants.O_RDONLY | fsSync.constants.O_NOFOLLOW);
+			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 {
@@ -1458,7 +1682,7 @@ var FilesystemBackend = class {
 			} catch {}
 			await fs.mkdir(path.dirname(resolvedPath), { recursive: true });
 			if (SUPPORTS_NOFOLLOW) {
-				const flags = fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_TRUNC | fsSync.constants.O_NOFOLLOW;
+				const flags = fs$1.constants.O_WRONLY | fs$1.constants.O_CREAT | fs$1.constants.O_TRUNC | fs$1.constants.O_NOFOLLOW;
 				const fd = await fs.open(resolvedPath, flags, 420);
 				try {
 					await fd.writeFile(content, "utf-8");
@@ -1484,7 +1708,7 @@ var FilesystemBackend = class {
 			let content;
 			if (SUPPORTS_NOFOLLOW) {
 				if (!(await fs.stat(resolvedPath)).isFile()) return { error: `Error: File '${filePath}' not found` };
-				const fd = await fs.open(resolvedPath, fsSync.constants.O_RDONLY | fsSync.constants.O_NOFOLLOW);
+				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 {
@@ -1500,7 +1724,7 @@ var FilesystemBackend = class {
 			if (typeof result === "string") return { error: result };
 			const [newContent, occurrences] = result;
 			if (SUPPORTS_NOFOLLOW) {
-				const flags = fsSync.constants.O_WRONLY | fsSync.constants.O_TRUNC | fsSync.constants.O_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");
@@ -1694,6 +1918,82 @@ var FilesystemBackend = class {
 		results.sort((a, b) => a.path.localeCompare(b.path));
 		return results;
 	}
+	/**
+	* Upload multiple files to the filesystem.
+	*
+	* @param files - List of [path, content] tuples to upload
+	* @returns List of FileUploadResponse objects, one per input file
+	*/
+	async uploadFiles(files) {
+		const responses = [];
+		for (const [filePath, content] of files) try {
+			const resolvedPath = this.resolvePath(filePath);
+			await fs.mkdir(path.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"
+			});
+		}
+		return responses;
+	}
+	/**
+	* Download multiple files from the filesystem.
+	*
+	* @param paths - List of file paths to download
+	* @returns List of FileDownloadResponse objects, one per input path
+	*/
+	async downloadFiles(paths) {
+		const responses = [];
+		for (const filePath of paths) try {
+			const resolvedPath = this.resolvePath(filePath);
+			const content = await 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"
+			});
+		}
+		return responses;
+	}
 };
 
 //#endregion
@@ -1861,6 +2161,465 @@ var CompositeBackend = class {
 		const [backend, strippedKey] = this.getBackendAndKey(filePath);
 		return await backend.edit(strippedKey, oldString, newString, replaceAll);
 	}
+	/**
+	* Execute a command via the default backend.
+	* Execution is not path-specific, so it always delegates to the default backend.
+	*
+	* @param command - Full shell command string to execute
+	* @returns ExecuteResponse with combined output, exit code, and truncation flag
+	* @throws Error if the default backend doesn't support command execution
+	*/
+	execute(command) {
+		if (!isSandboxBackend(this.default)) throw new Error("Default backend doesn't support command execution (SandboxBackendProtocol). To enable execution, provide a default backend that implements SandboxBackendProtocol.");
+		return Promise.resolve(this.default.execute(command));
+	}
+	/**
+	* Upload multiple files, batching by backend for efficiency.
+	*
+	* @param files - List of [path, content] tuples to upload
+	* @returns List of FileUploadResponse objects, one per input file
+	*/
+	async uploadFiles(files) {
+		const results = new Array(files.length).fill(null);
+		const batchesByBackend = /* @__PURE__ */ new Map();
+		for (let idx = 0; idx < files.length; idx++) {
+			const [path$1, content] = files[idx];
+			const [backend, strippedPath] = this.getBackendAndKey(path$1);
+			if (!batchesByBackend.has(backend)) batchesByBackend.set(backend, []);
+			batchesByBackend.get(backend).push({
+				idx,
+				path: strippedPath,
+				content
+			});
+		}
+		for (const [backend, batch] of batchesByBackend) {
+			const batchFiles = batch.map((b) => [b.path, b.content]);
+			const batchResponses = await backend.uploadFiles(batchFiles);
+			for (let i = 0; i < batch.length; i++) {
+				const originalIdx = batch[i].idx;
+				results[originalIdx] = {
+					path: files[originalIdx][0],
+					error: batchResponses[i]?.error ?? null
+				};
+			}
+		}
+		return results;
+	}
+	/**
+	* Download multiple files, batching by backend for efficiency.
+	*
+	* @param paths - List of file paths to download
+	* @returns List of FileDownloadResponse objects, one per input path
+	*/
+	async downloadFiles(paths) {
+		const results = new Array(paths.length).fill(null);
+		const batchesByBackend = /* @__PURE__ */ new Map();
+		for (let idx = 0; idx < paths.length; idx++) {
+			const path$1 = paths[idx];
+			const [backend, strippedPath] = this.getBackendAndKey(path$1);
+			if (!batchesByBackend.has(backend)) batchesByBackend.set(backend, []);
+			batchesByBackend.get(backend).push({
+				idx,
+				path: strippedPath
+			});
+		}
+		for (const [backend, batch] of batchesByBackend) {
+			const batchPaths = batch.map((b) => b.path);
+			const batchResponses = await backend.downloadFiles(batchPaths);
+			for (let i = 0; i < batch.length; i++) {
+				const originalIdx = batch[i].idx;
+				results[originalIdx] = {
+					path: paths[originalIdx],
+					content: batchResponses[i]?.content ?? null,
+					error: batchResponses[i]?.error ?? null
+				};
+			}
+		}
+		return results;
+	}
+};
+
+//#endregion
+//#region src/backends/sandbox.ts
+/**
+* Node.js command template for glob operations.
+* Uses web-standard atob() for base64 decoding.
+*/
+function buildGlobCommand(searchPath, pattern) {
+	return `node -e "
+const fs = require('fs');
+const path = require('path');
+
+const searchPath = atob('${btoa(searchPath)}');
+const pattern = atob('${btoa(pattern)}');
+
+function globMatch(relativePath, pattern) {
+  const regexPattern = pattern
+    .replace(/\\*\\*/g, '<<<GLOBSTAR>>>')
+    .replace(/\\*/g, '[^/]*')
+    .replace(/\\?/g, '.')
+    .replace(/<<<GLOBSTAR>>>/g, '.*');
+  return new RegExp('^' + regexPattern + '$').test(relativePath);
+}
+
+function walkDir(dir, baseDir, results) {
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const relativePath = path.relative(baseDir, fullPath);
+      if (entry.isDirectory()) {
+        walkDir(fullPath, baseDir, results);
+      } else if (globMatch(relativePath, pattern)) {
+        const stat = fs.statSync(fullPath);
+        console.log(JSON.stringify({
+          path: relativePath,
+          size: stat.size,
+          mtime: stat.mtimeMs,
+          isDir: false
+        }));
+      }
+    }
+  } catch (e) {
+    // Silent failure for non-existent paths
+  }
+}
+
+try {
+  process.chdir(searchPath);
+  walkDir('.', '.', []);
+} catch (e) {
+  // Silent failure for non-existent paths
+}
+"`;
+}
+/**
+* Node.js command template for listing directory contents.
+*/
+function buildLsCommand(dirPath) {
+	return `node -e "
+const fs = require('fs');
+const path = require('path');
+
+const dirPath = atob('${btoa(dirPath)}');
+
+try {
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+    const stat = fs.statSync(fullPath);
+    console.log(JSON.stringify({
+      path: entry.isDirectory() ? fullPath + '/' : fullPath,
+      size: stat.size,
+      mtime: stat.mtimeMs,
+      isDir: entry.isDirectory()
+    }));
+  }
+} catch (e) {
+  console.error('Error: ' + e.message);
+  process.exit(1);
+}
+"`;
+}
+/**
+* Node.js command template for reading files.
+*/
+function buildReadCommand(filePath, offset, limit) {
+	return `node -e "
+const fs = require('fs');
+
+const filePath = atob('${btoa(filePath)}');
+const offset = ${Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 0};
+const limit = ${Number.isFinite(limit) && limit > 0 && limit < Number.MAX_SAFE_INTEGER ? Math.floor(limit) : 0};
+
+if (!fs.existsSync(filePath)) {
+  console.log('Error: File not found');
+  process.exit(1);
+}
+
+const stat = fs.statSync(filePath);
+if (stat.size === 0) {
+  console.log('System reminder: File exists but has empty contents');
+  process.exit(0);
+}
+
+const content = fs.readFileSync(filePath, 'utf-8');
+const lines = content.split('\\n');
+const selected = lines.slice(offset, offset + limit);
+
+for (let i = 0; i < selected.length; i++) {
+  const lineNum = offset + i + 1;
+  console.log(String(lineNum).padStart(6) + '\\t' + selected[i]);
+}
+"`;
+}
+/**
+* Node.js command template for writing files.
+*/
+function buildWriteCommand(filePath, content) {
+	return `node -e "
+const fs = require('fs');
+const path = require('path');
+
+const filePath = atob('${btoa(filePath)}');
+const content = atob('${btoa(content)}');
+
+if (fs.existsSync(filePath)) {
+  console.error('Error: File already exists');
+  process.exit(1);
+}
+
+const parentDir = path.dirname(filePath) || '.';
+fs.mkdirSync(parentDir, { recursive: true });
+
+fs.writeFileSync(filePath, content, 'utf-8');
+console.log('OK');
+"`;
+}
+/**
+* Node.js command template for editing files.
+*/
+function buildEditCommand(filePath, oldStr, newStr, replaceAll) {
+	return `node -e "
+const fs = require('fs');
+
+const filePath = atob('${btoa(filePath)}');
+const oldStr = atob('${btoa(oldStr)}');
+const newStr = atob('${btoa(newStr)}');
+const replaceAll = ${Boolean(replaceAll)};
+
+let text;
+try {
+  text = fs.readFileSync(filePath, 'utf-8');
+} catch (e) {
+  process.exit(3);
+}
+
+const count = text.split(oldStr).length - 1;
+
+if (count === 0) {
+  process.exit(1);
+}
+if (count > 1 && !replaceAll) {
+  process.exit(2);
+}
+
+const result = text.split(oldStr).join(newStr);
+fs.writeFileSync(filePath, result, 'utf-8');
+console.log(count);
+"`;
+}
+/**
+* Node.js command template for grep operations.
+*/
+function buildGrepCommand(pattern, searchPath, globPattern) {
+	const patternB64 = btoa(pattern);
+	const pathB64 = btoa(searchPath);
+	const globB64 = globPattern ? btoa(globPattern) : "";
+	return `node -e "
+const fs = require('fs');
+const path = require('path');
+
+const pattern = atob('${patternB64}');
+const searchPath = atob('${pathB64}');
+const globPattern = ${globPattern ? `atob('${globB64}')` : "null"};
+
+let regex;
+try {
+  regex = new RegExp(pattern);
+} catch (e) {
+  console.error('Invalid regex: ' + e.message);
+  process.exit(1);
+}
+
+function globMatch(filePath, pattern) {
+  if (!pattern) return true;
+  const regexPattern = pattern
+    .replace(/\\*\\*/g, '<<<GLOBSTAR>>>')
+    .replace(/\\*/g, '[^/]*')
+    .replace(/\\?/g, '.')
+    .replace(/<<<GLOBSTAR>>>/g, '.*');
+  return new RegExp('^' + regexPattern + '$').test(filePath);
+}
+
+function walkDir(dir, results) {
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walkDir(fullPath, results);
+      } else {
+        const relativePath = path.relative(searchPath, fullPath);
+        if (globMatch(relativePath, globPattern)) {
+          try {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            const lines = content.split('\\n');
+            for (let i = 0; i < lines.length; i++) {
+              if (regex.test(lines[i])) {
+                console.log(JSON.stringify({
+                  path: fullPath,
+                  line: i + 1,
+                  text: lines[i]
+                }));
+              }
+            }
+          } catch (e) {
+            // Skip unreadable files
+          }
+        }
+      }
+    }
+  } catch (e) {
+    // Skip unreadable directories
+  }
+}
+
+try {
+  walkDir(searchPath, []);
+} catch (e) {
+  // Silent failure
+}
+"`;
+}
+/**
+* Base sandbox implementation with execute() as the only abstract method.
+*
+* This class provides default implementations for all SandboxBackendProtocol
+* methods using shell commands executed via execute(). Concrete implementations
+* only need to implement the execute() method.
+*
+* Requires Node.js 20+ on the sandbox host.
+*/
+var BaseSandbox = class {
+	/**
+	* List files and directories in the specified directory (non-recursive).
+	*
+	* @param path - Absolute path to directory
+	* @returns List of FileInfo objects for files and directories directly in the directory.
+	*/
+	async lsInfo(path$1) {
+		const command = buildLsCommand(path$1);
+		const result = await this.execute(command);
+		if (result.exitCode !== 0) return [];
+		const infos = [];
+		const lines = result.output.trim().split("\n").filter(Boolean);
+		for (const line of lines) try {
+			const parsed = JSON.parse(line);
+			infos.push({
+				path: parsed.path,
+				is_dir: parsed.isDir,
+				size: parsed.size,
+				modified_at: parsed.mtime ? new Date(parsed.mtime).toISOString() : void 0
+			});
+		} catch {}
+		return infos;
+	}
+	/**
+	* Read file content with line numbers.
+	*
+	* @param filePath - Absolute file path
+	* @param offset - Line offset to start reading from (0-indexed)
+	* @param limit - Maximum number of lines to read
+	* @returns Formatted file content with line numbers, or error message
+	*/
+	async read(filePath, offset = 0, limit = 2e3) {
+		const command = buildReadCommand(filePath, offset, limit);
+		const result = await this.execute(command);
+		if (result.exitCode !== 0) return `Error: File '${filePath}' not found`;
+		return result.output;
+	}
+	/**
+	* Read file content as raw FileData.
+	*
+	* @param filePath - Absolute file path
+	* @returns Raw file content as FileData
+	*/
+	async readRaw(filePath) {
+		const command = buildReadCommand(filePath, 0, Number.MAX_SAFE_INTEGER);
+		const result = await this.execute(command);
+		if (result.exitCode !== 0) throw new Error(`File '${filePath}' not found`);
+		const lines = [];
+		for (const line of result.output.split("\n")) {
+			const tabIndex = line.indexOf("	");
+			if (tabIndex !== -1) lines.push(line.substring(tabIndex + 1));
+		}
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		return {
+			content: lines,
+			created_at: now,
+			modified_at: now
+		};
+	}
+	/**
+	* Structured search results or error string for invalid input.
+	*/
+	async grepRaw(pattern, path$1 = "/", glob = null) {
+		const command = buildGrepCommand(pattern, path$1, glob);
+		const result = await this.execute(command);
+		if (result.exitCode === 1) {
+			if (result.output.includes("Invalid regex:")) return result.output.trim();
+		}
+		const matches = [];
+		const lines = result.output.trim().split("\n").filter(Boolean);
+		for (const line of lines) try {
+			const parsed = JSON.parse(line);
+			matches.push({
+				path: parsed.path,
+				line: parsed.line,
+				text: parsed.text
+			});
+		} catch {}
+		return matches;
+	}
+	/**
+	* Structured glob matching returning FileInfo objects.
+	*/
+	async globInfo(pattern, path$1 = "/") {
+		const command = buildGlobCommand(path$1, pattern);
+		const result = await this.execute(command);
+		const infos = [];
+		const lines = result.output.trim().split("\n").filter(Boolean);
+		for (const line of lines) try {
+			const parsed = JSON.parse(line);
+			infos.push({
+				path: parsed.path,
+				is_dir: parsed.isDir,
+				size: parsed.size,
+				modified_at: parsed.mtime ? new Date(parsed.mtime).toISOString() : void 0
+			});
+		} catch {}
+		return infos;
+	}
+	/**
+	* Create a new file with content.
+	*/
+	async write(filePath, content) {
+		const command = buildWriteCommand(filePath, content);
+		if ((await this.execute(command)).exitCode !== 0) return { error: `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.` };
+		return {
+			path: filePath,
+			filesUpdate: null
+		};
+	}
+	/**
+	* Edit a file by replacing string occurrences.
+	*/
+	async edit(filePath, oldString, newString, replaceAll = false) {
+		const command = buildEditCommand(filePath, oldString, newString, replaceAll);
+		const result = await this.execute(command);
+		switch (result.exitCode) {
+			case 0: return {
+				path: filePath,
+				filesUpdate: null,
+				occurrences: parseInt(result.output.trim(), 10) || 1
+			};
+			case 1: return { error: `String not found in file '${filePath}'` };
+			case 2: return { error: `Multiple occurrences found in '${filePath}'. Use replaceAll=true to replace all.` };
+			case 3: return { error: `Error: File '${filePath}' not found` };
+			default: return { error: `Unknown error editing file '${filePath}'` };
+		}
+	}
 };
 
 //#endregion
@@ -1930,4 +2689,691 @@ function createDeepAgent(params = {}) {
 }
 
 //#endregion
-export { CompositeBackend, FilesystemBackend, StateBackend, StoreBackend, createDeepAgent, createFilesystemMiddleware, createPatchToolCallsMiddleware, createSubAgentMiddleware };
+//#region src/config.ts
+/**
+* Configuration and settings for deepagents.
+*
+* Provides project detection, path management, and environment configuration
+* for skills and agent memory middleware.
+*/
+/**
+* Find the project root by looking for .git directory.
+*
+* Walks up the directory tree from startPath (or cwd) looking for a .git
+* directory, which indicates the project root.
+*
+* @param startPath - Directory to start searching from. Defaults to current working directory.
+* @returns Path to the project root if found, null otherwise.
+*/
+function findProjectRoot(startPath) {
+	let current = path.resolve(startPath || process.cwd());
+	while (current !== path.dirname(current)) {
+		const gitDir = path.join(current, ".git");
+		if (fs$1.existsSync(gitDir)) return current;
+		current = path.dirname(current);
+	}
+	const rootGitDir = path.join(current, ".git");
+	if (fs$1.existsSync(rootGitDir)) return current;
+	return null;
+}
+/**
+* Validate agent name to prevent invalid filesystem paths and security issues.
+*
+* @param agentName - The agent name to validate
+* @returns True if valid, false otherwise
+*/
+function isValidAgentName(agentName) {
+	if (!agentName || !agentName.trim()) return false;
+	return /^[a-zA-Z0-9_\-\s]+$/.test(agentName);
+}
+/**
+* Create a Settings instance with detected environment.
+*
+* @param options - Configuration options
+* @returns Settings instance with project detection and path management
+*/
+function createSettings(options = {}) {
+	const projectRoot = findProjectRoot(options.startPath);
+	const userDeepagentsDir = path.join(os.homedir(), ".deepagents");
+	return {
+		projectRoot,
+		userDeepagentsDir,
+		hasProject: projectRoot !== null,
+		getAgentDir(agentName) {
+			if (!isValidAgentName(agentName)) throw new Error(`Invalid agent name: ${JSON.stringify(agentName)}. Agent names can only contain letters, numbers, hyphens, underscores, and spaces.`);
+			return path.join(userDeepagentsDir, agentName);
+		},
+		ensureAgentDir(agentName) {
+			const agentDir = this.getAgentDir(agentName);
+			fs$1.mkdirSync(agentDir, { recursive: true });
+			return agentDir;
+		},
+		getUserAgentMdPath(agentName) {
+			return path.join(this.getAgentDir(agentName), "agent.md");
+		},
+		getProjectAgentMdPath() {
+			if (!projectRoot) return null;
+			return path.join(projectRoot, ".deepagents", "agent.md");
+		},
+		getUserSkillsDir(agentName) {
+			return path.join(this.getAgentDir(agentName), "skills");
+		},
+		ensureUserSkillsDir(agentName) {
+			const skillsDir = this.getUserSkillsDir(agentName);
+			fs$1.mkdirSync(skillsDir, { recursive: true });
+			return skillsDir;
+		},
+		getProjectSkillsDir() {
+			if (!projectRoot) return null;
+			return path.join(projectRoot, ".deepagents", "skills");
+		},
+		ensureProjectSkillsDir() {
+			const skillsDir = this.getProjectSkillsDir();
+			if (!skillsDir) return null;
+			fs$1.mkdirSync(skillsDir, { recursive: true });
+			return skillsDir;
+		},
+		ensureProjectDeepagentsDir() {
+			if (!projectRoot) return null;
+			const deepagentsDir = path.join(projectRoot, ".deepagents");
+			fs$1.mkdirSync(deepagentsDir, { recursive: true });
+			return deepagentsDir;
+		}
+	};
+}
+
+//#endregion
+//#region src/skills/loader.ts
+/**
+* Skill loader for parsing and loading agent skills from SKILL.md files.
+*
+* This module implements Anthropic's agent skills pattern with YAML frontmatter parsing.
+* Each skill is a directory containing a SKILL.md file with:
+* - YAML frontmatter (name, description required)
+* - Markdown instructions for the agent
+* - Optional supporting files (scripts, configs, etc.)
+*
+* @example
+* ```markdown
+* ---
+* name: web-research
+* description: Structured approach to conducting thorough web research
+* ---
+*
+* # Web Research Skill
+*
+* ## When to Use
+* - User asks you to research a topic
+* ...
+* ```
+*
+* @see https://agentskills.io/specification
+*/
+/** Maximum size for SKILL.md files (10MB) */
+const MAX_SKILL_FILE_SIZE = 10 * 1024 * 1024;
+/** Agent Skills spec constraints */
+const MAX_SKILL_NAME_LENGTH = 64;
+const MAX_SKILL_DESCRIPTION_LENGTH = 1024;
+/** Pattern for validating skill names per Agent Skills spec */
+const SKILL_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/** Pattern for extracting YAML frontmatter */
+const FRONTMATTER_PATTERN = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+/**
+* Check if a path is safely contained within base_dir.
+*
+* This prevents directory traversal attacks via symlinks or path manipulation.
+* The function resolves both paths to their canonical form (following symlinks)
+* and verifies that the target path is within the base directory.
+*
+* @param targetPath - The path to validate
+* @param baseDir - The base directory that should contain the path
+* @returns True if the path is safely within baseDir, false otherwise
+*/
+function isSafePath(targetPath, baseDir) {
+	try {
+		const resolvedPath = fs$1.realpathSync(targetPath);
+		const resolvedBase = fs$1.realpathSync(baseDir);
+		return resolvedPath.startsWith(resolvedBase + path.sep) || resolvedPath === resolvedBase;
+	} catch {
+		return false;
+	}
+}
+/**
+* Validate skill name per Agent Skills spec.
+*
+* Requirements:
+* - Max 64 characters
+* - Lowercase alphanumeric and hyphens only (a-z, 0-9, -)
+* - Cannot start or end with hyphen
+* - No consecutive hyphens
+* - Must match parent directory name
+*
+* @param name - The skill name from YAML frontmatter
+* @param directoryName - The parent directory name
+* @returns Validation result with error message if invalid
+*/
+function validateSkillName(name, directoryName) {
+	if (!name) return {
+		valid: false,
+		error: "name is required"
+	};
+	if (name.length > MAX_SKILL_NAME_LENGTH) return {
+		valid: false,
+		error: "name exceeds 64 characters"
+	};
+	if (!SKILL_NAME_PATTERN.test(name)) return {
+		valid: false,
+		error: "name must be lowercase alphanumeric with single hyphens only"
+	};
+	if (name !== directoryName) return {
+		valid: false,
+		error: `name '${name}' must match directory name '${directoryName}'`
+	};
+	return { valid: true };
+}
+/**
+* Parse YAML frontmatter from content.
+*
+* @param content - The file content
+* @returns Parsed frontmatter object, or null if parsing fails
+*/
+function parseFrontmatter(content) {
+	const match = content.match(FRONTMATTER_PATTERN);
+	if (!match) return null;
+	try {
+		const parsed = yaml.parse(match[1]);
+		return typeof parsed === "object" && parsed !== null ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Parse YAML frontmatter from a SKILL.md file per Agent Skills spec.
+*
+* @param skillMdPath - Path to the SKILL.md file
+* @param source - Source of the skill ('user' or 'project')
+* @returns SkillMetadata with all fields, or null if parsing fails
+*/
+function parseSkillMetadata(skillMdPath, source) {
+	try {
+		const stats = fs$1.statSync(skillMdPath);
+		if (stats.size > MAX_SKILL_FILE_SIZE) {
+			console.warn(`Skipping ${skillMdPath}: file too large (${stats.size} bytes)`);
+			return null;
+		}
+		const frontmatter = parseFrontmatter(fs$1.readFileSync(skillMdPath, "utf-8"));
+		if (!frontmatter) {
+			console.warn(`Skipping ${skillMdPath}: no valid YAML frontmatter found`);
+			return null;
+		}
+		const name = frontmatter.name;
+		const description = frontmatter.description;
+		if (!name || !description) {
+			console.warn(`Skipping ${skillMdPath}: missing required 'name' or 'description'`);
+			return null;
+		}
+		const directoryName = path.basename(path.dirname(skillMdPath));
+		const validation = validateSkillName(String(name), directoryName);
+		if (!validation.valid) console.warn(`Skill '${name}' in ${skillMdPath} does not follow Agent Skills spec: ${validation.error}. Consider renaming to be spec-compliant.`);
+		let descriptionStr = String(description);
+		if (descriptionStr.length > MAX_SKILL_DESCRIPTION_LENGTH) {
+			console.warn(`Description exceeds ${MAX_SKILL_DESCRIPTION_LENGTH} chars in ${skillMdPath}, truncating`);
+			descriptionStr = descriptionStr.slice(0, MAX_SKILL_DESCRIPTION_LENGTH);
+		}
+		return {
+			name: String(name),
+			description: descriptionStr,
+			path: skillMdPath,
+			source,
+			license: frontmatter.license ? String(frontmatter.license) : void 0,
+			compatibility: frontmatter.compatibility ? String(frontmatter.compatibility) : void 0,
+			metadata: frontmatter.metadata && typeof frontmatter.metadata === "object" ? frontmatter.metadata : void 0,
+			allowedTools: frontmatter["allowed-tools"] ? String(frontmatter["allowed-tools"]) : void 0
+		};
+	} catch (error) {
+		console.warn(`Error reading ${skillMdPath}: ${error}`);
+		return null;
+	}
+}
+/**
+* List all skills from a single skills directory (internal helper).
+*
+* Scans the skills directory for subdirectories containing SKILL.md files,
+* parses YAML frontmatter, and returns skill metadata.
+*
+* Skills are organized as:
+* ```
+* skills/
+* ├── skill-name/
+* │   ├── SKILL.md        # Required: instructions with YAML frontmatter
+* │   ├── script.py       # Optional: supporting files
+* │   └── config.json     # Optional: supporting files
+* ```
+*
+* @param skillsDir - Path to the skills directory
+* @param source - Source of the skills ('user' or 'project')
+* @returns List of skill metadata
+*/
+function listSkillsFromDir(skillsDir, source) {
+	const expandedDir = skillsDir.startsWith("~") ? path.join(process.env.HOME || process.env.USERPROFILE || "", skillsDir.slice(1)) : skillsDir;
+	if (!fs$1.existsSync(expandedDir)) return [];
+	let resolvedBase;
+	try {
+		resolvedBase = fs$1.realpathSync(expandedDir);
+	} catch {
+		return [];
+	}
+	const skills = [];
+	let entries;
+	try {
+		entries = fs$1.readdirSync(resolvedBase, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	for (const entry of entries) {
+		const skillDir = path.join(resolvedBase, entry.name);
+		if (!isSafePath(skillDir, resolvedBase)) continue;
+		if (!entry.isDirectory()) continue;
+		const skillMdPath = path.join(skillDir, "SKILL.md");
+		if (!fs$1.existsSync(skillMdPath)) continue;
+		if (!isSafePath(skillMdPath, resolvedBase)) continue;
+		const metadata = parseSkillMetadata(skillMdPath, source);
+		if (metadata) skills.push(metadata);
+	}
+	return skills;
+}
+/**
+* List skills from user and/or project directories.
+*
+* When both directories are provided, project skills with the same name as
+* user skills will override them.
+*
+* @param options - Options specifying which directories to search
+* @returns Merged list of skill metadata from both sources, with project skills
+*          taking precedence over user skills when names conflict
+*/
+function listSkills(options) {
+	const allSkills = /* @__PURE__ */ new Map();
+	if (options.userSkillsDir) {
+		const userSkills = listSkillsFromDir(options.userSkillsDir, "user");
+		for (const skill of userSkills) allSkills.set(skill.name, skill);
+	}
+	if (options.projectSkillsDir) {
+		const projectSkills = listSkillsFromDir(options.projectSkillsDir, "project");
+		for (const skill of projectSkills) allSkills.set(skill.name, skill);
+	}
+	return Array.from(allSkills.values());
+}
+
+//#endregion
+//#region src/middleware/skills.ts
+/**
+* Middleware for loading and exposing agent skills to the system prompt.
+*
+* This middleware implements Anthropic's "Agent Skills" pattern with progressive disclosure:
+* 1. Parse YAML frontmatter from SKILL.md files at session start
+* 2. Inject skills metadata (name + description) into system prompt
+* 3. Agent reads full SKILL.md content when relevant to a task
+*
+* Skills directory structure (per-agent + project):
+* User-level: ~/.deepagents/{AGENT_NAME}/skills/
+* Project-level: {PROJECT_ROOT}/.deepagents/skills/
+*
+* @example
+* ```
+* ~/.deepagents/{AGENT_NAME}/skills/
+* ├── web-research/
+* │   ├── SKILL.md        # Required: YAML frontmatter + instructions
+* │   └── helper.py       # Optional: supporting files
+* ├── code-review/
+* │   ├── SKILL.md
+* │   └── checklist.md
+*
+* .deepagents/skills/
+* ├── project-specific/
+* │   └── SKILL.md        # Project-specific skills
+* ```
+*/
+/**
+* State schema for skills middleware.
+*/
+const SkillsStateSchema = z$2.object({ skillsMetadata: z$2.array(z$2.object({
+	name: z$2.string(),
+	description: z$2.string(),
+	path: z$2.string(),
+	source: z$2.enum(["user", "project"]),
+	license: z$2.string().optional(),
+	compatibility: z$2.string().optional(),
+	metadata: z$2.record(z$2.string(), z$2.string()).optional(),
+	allowedTools: z$2.string().optional()
+})).optional() });
+/**
+* Skills System Documentation prompt template.
+*/
+const SKILLS_SYSTEM_PROMPT = `
+
+## Skills System
+
+You have access to a skills library that provides specialized capabilities and domain knowledge.
+
+{skills_locations}
+
+**Available Skills:**
+
+{skills_list}
+
+**How to Use Skills (Progressive Disclosure):**
+
+Skills follow a **progressive disclosure** pattern - you know they exist (name + description above), but you only read the full instructions when needed:
+
+1. **Recognize when a skill applies**: Check if the user's task matches any skill's description
+2. **Read the skill's full instructions**: The skill list above shows the exact path to use with read_file
+3. **Follow the skill's instructions**: SKILL.md contains step-by-step workflows, best practices, and examples
+4. **Access supporting files**: Skills may include Python scripts, configs, or reference docs - use absolute paths
+
+**When to Use Skills:**
+- When the user's request matches a skill's domain (e.g., "research X" → web-research skill)
+- When you need specialized knowledge or structured workflows
+- When a skill provides proven patterns for complex tasks
+
+**Skills are Self-Documenting:**
+- Each SKILL.md tells you exactly what the skill does and how to use it
+- The skill list above shows the full path for each skill's SKILL.md file
+
+**Executing Skill Scripts:**
+Skills may contain Python scripts or other executable files. Always use absolute paths from the skill list.
+
+**Example Workflow:**
+
+User: "Can you research the latest developments in quantum computing?"
+
+1. Check available skills above → See "web-research" skill with its full path
+2. Read the skill using the path shown in the list
+3. Follow the skill's research workflow (search → organize → synthesize)
+4. Use any helper scripts with absolute paths
+
+Remember: Skills are tools to make you more capable and consistent. When in doubt, check if a skill exists for the task!
+`;
+/**
+* Format skills locations for display in system prompt.
+*/
+function formatSkillsLocations(userSkillsDisplay, projectSkillsDir) {
+	const locations = [`**User Skills**: \`${userSkillsDisplay}\``];
+	if (projectSkillsDir) locations.push(`**Project Skills**: \`${projectSkillsDir}\` (overrides user skills)`);
+	return locations.join("\n");
+}
+/**
+* Format skills metadata for display in system prompt.
+*/
+function formatSkillsList(skills, userSkillsDisplay, projectSkillsDir) {
+	if (skills.length === 0) {
+		const locations = [userSkillsDisplay];
+		if (projectSkillsDir) locations.push(projectSkillsDir);
+		return `(No skills available yet. You can create skills in ${locations.join(" or ")})`;
+	}
+	const userSkills = skills.filter((s) => s.source === "user");
+	const projectSkills = skills.filter((s) => s.source === "project");
+	const lines = [];
+	if (userSkills.length > 0) {
+		lines.push("**User Skills:**");
+		for (const skill of userSkills) {
+			lines.push(`- **${skill.name}**: ${skill.description}`);
+			lines.push(`  → Read \`${skill.path}\` for full instructions`);
+		}
+		lines.push("");
+	}
+	if (projectSkills.length > 0) {
+		lines.push("**Project Skills:**");
+		for (const skill of projectSkills) {
+			lines.push(`- **${skill.name}**: ${skill.description}`);
+			lines.push(`  → Read \`${skill.path}\` for full instructions`);
+		}
+	}
+	return lines.join("\n");
+}
+/**
+* Create middleware for loading and exposing agent skills.
+*
+* This middleware implements Anthropic's agent skills pattern:
+* - Loads skills metadata (name, description) from YAML frontmatter at session start
+* - Injects skills list into system prompt for discoverability
+* - Agent reads full SKILL.md content when a skill is relevant (progressive disclosure)
+*
+* Supports both user-level and project-level skills:
+* - User skills: ~/.deepagents/{AGENT_NAME}/skills/
+* - Project skills: {PROJECT_ROOT}/.deepagents/skills/
+* - Project skills override user skills with the same name
+*
+* @param options - Configuration options
+* @returns AgentMiddleware for skills loading and injection
+*/
+function createSkillsMiddleware(options) {
+	const { skillsDir, assistantId, projectSkillsDir } = options;
+	const userSkillsDisplay = `~/.deepagents/${assistantId}/skills`;
+	return createMiddleware({
+		name: "SkillsMiddleware",
+		stateSchema: SkillsStateSchema,
+		beforeAgent() {
+			return { skillsMetadata: listSkills({
+				userSkillsDir: skillsDir,
+				projectSkillsDir
+			}) };
+		},
+		wrapModelCall(request, handler) {
+			const skillsMetadata = request.state?.skillsMetadata || [];
+			const skillsLocations = formatSkillsLocations(userSkillsDisplay, projectSkillsDir);
+			const skillsList = formatSkillsList(skillsMetadata, userSkillsDisplay, projectSkillsDir);
+			const skillsSection = SKILLS_SYSTEM_PROMPT.replace("{skills_locations}", skillsLocations).replace("{skills_list}", skillsList);
+			const currentSystemPrompt = request.systemPrompt || "";
+			const newSystemPrompt = currentSystemPrompt ? `${currentSystemPrompt}\n\n${skillsSection}` : skillsSection;
+			return handler({
+				...request,
+				systemPrompt: newSystemPrompt
+			});
+		}
+	});
+}
+
+//#endregion
+//#region src/middleware/agent-memory.ts
+/**
+* Middleware for loading agent-specific long-term memory into the system prompt.
+*
+* This middleware loads the agent's long-term memory from agent.md files
+* and injects it into the system prompt. Memory is loaded from:
+* - User memory: ~/.deepagents/{agent_name}/agent.md
+* - Project memory: {project_root}/.deepagents/agent.md
+*/
+/**
+* State schema for agent memory middleware.
+*/
+const AgentMemoryStateSchema = z$2.object({
+	userMemory: z$2.string().optional(),
+	projectMemory: z$2.string().optional()
+});
+/**
+* Default template for memory injection.
+*/
+const DEFAULT_MEMORY_TEMPLATE = `<user_memory>
+{user_memory}
+</user_memory>
+
+<project_memory>
+{project_memory}
+</project_memory>`;
+/**
+* Long-term Memory Documentation system prompt.
+*/
+const LONGTERM_MEMORY_SYSTEM_PROMPT = `
+
+## Long-term Memory
+
+Your long-term memory is stored in files on the filesystem and persists across sessions.
+
+**User Memory Location**: \`{agent_dir_absolute}\` (displays as \`{agent_dir_display}\`)
+**Project Memory Location**: {project_memory_info}
+
+Your system prompt is loaded from TWO sources at startup:
+1. **User agent.md**: \`{agent_dir_absolute}/agent.md\` - Your personal preferences across all projects
+2. **Project agent.md**: Loaded from project root if available - Project-specific instructions
+
+Project-specific agent.md is loaded from these locations (both combined if both exist):
+- \`[project-root]/.deepagents/agent.md\` (preferred)
+- \`[project-root]/agent.md\` (fallback, but also included if both exist)
+
+**When to CHECK/READ memories (CRITICAL - do this FIRST):**
+- **At the start of ANY new session**: Check both user and project memories
+  - User: \`ls {agent_dir_absolute}\`
+  - Project: \`ls {project_deepagents_dir}\` (if in a project)
+- **BEFORE answering questions**: If asked "what do you know about X?" or "how do I do Y?", check project memories FIRST, then user
+- **When user asks you to do something**: Check if you have project-specific guides or examples
+- **When user references past work**: Search project memory files for related context
+
+**Memory-first response pattern:**
+1. User asks a question → Check project directory first: \`ls {project_deepagents_dir}\`
+2. If relevant files exist → Read them with \`read_file '{project_deepagents_dir}/[filename]'\`
+3. Check user memory if needed → \`ls {agent_dir_absolute}\`
+4. Base your answer on saved knowledge supplemented by general knowledge
+
+**When to update memories:**
+- **IMMEDIATELY when the user describes your role or how you should behave**
+- **IMMEDIATELY when the user gives feedback on your work** - Update memories to capture what was wrong and how to do it better
+- When the user explicitly asks you to remember something
+- When patterns or preferences emerge (coding styles, conventions, workflows)
+- After significant work where context would help in future sessions
+
+**Learning from feedback:**
+- When user says something is better/worse, capture WHY and encode it as a pattern
+- Each correction is a chance to improve permanently - don't just fix the immediate issue, update your instructions
+- When user says "you should remember X" or "be careful about Y", treat this as HIGH PRIORITY - update memories IMMEDIATELY
+- Look for the underlying principle behind corrections, not just the specific mistake
+
+## Deciding Where to Store Memory
+
+When writing or updating agent memory, decide whether each fact, configuration, or behavior belongs in:
+
+### User Agent File: \`{agent_dir_absolute}/agent.md\`
+→ Describes the agent's **personality, style, and universal behavior** across all projects.
+
+**Store here:**
+- Your general tone and communication style
+- Universal coding preferences (formatting, comment style, etc.)
+- General workflows and methodologies you follow
+- Tool usage patterns that apply everywhere
+- Personal preferences that don't change per-project
+
+**Examples:**
+- "Be concise and direct in responses"
+- "Always use type hints in Python"
+- "Prefer functional programming patterns"
+
+### Project Agent File: \`{project_deepagents_dir}/agent.md\`
+→ Describes **how this specific project works** and **how the agent should behave here only.**
+
+**Store here:**
+- Project-specific architecture and design patterns
+- Coding conventions specific to this codebase
+- Project structure and organization
+- Testing strategies for this project
+- Deployment processes and workflows
+- Team conventions and guidelines
+
+**Examples:**
+- "This project uses FastAPI with SQLAlchemy"
+- "Tests go in tests/ directory mirroring src/ structure"
+- "All API changes require updating OpenAPI spec"
+
+### Project Memory Files: \`{project_deepagents_dir}/*.md\`
+→ Use for **project-specific reference information** and structured notes.
+
+**Store here:**
+- API design documentation
+- Architecture decisions and rationale
+- Deployment procedures
+- Common debugging patterns
+- Onboarding information
+
+**Examples:**
+- \`{project_deepagents_dir}/api-design.md\` - REST API patterns used
+- \`{project_deepagents_dir}/architecture.md\` - System architecture overview
+- \`{project_deepagents_dir}/deployment.md\` - How to deploy this project
+
+### File Operations:
+
+**User memory:**
+\`\`\`
+ls {agent_dir_absolute}                              # List user memory files
+read_file '{agent_dir_absolute}/agent.md'            # Read user preferences
+edit_file '{agent_dir_absolute}/agent.md' ...        # Update user preferences
+\`\`\`
+
+**Project memory (preferred for project-specific information):**
+\`\`\`
+ls {project_deepagents_dir}                          # List project memory files
+read_file '{project_deepagents_dir}/agent.md'        # Read project instructions
+edit_file '{project_deepagents_dir}/agent.md' ...    # Update project instructions
+write_file '{project_deepagents_dir}/agent.md' ...  # Create project memory file
+\`\`\`
+
+**Important**:
+- Project memory files are stored in \`.deepagents/\` inside the project root
+- Always use absolute paths for file operations
+- Check project memories BEFORE user when answering project-specific questions`;
+/**
+* Create middleware for loading agent-specific long-term memory.
+*
+* This middleware loads the agent's long-term memory from a file (agent.md)
+* and injects it into the system prompt. The memory is loaded once at the
+* start of the conversation and stored in state.
+*
+* @param options - Configuration options
+* @returns AgentMiddleware for memory loading and injection
+*/
+function createAgentMemoryMiddleware(options) {
+	const { settings, assistantId, systemPromptTemplate } = options;
+	const agentDir = settings.getAgentDir(assistantId);
+	const agentDirDisplay = `~/.deepagents/${assistantId}`;
+	const agentDirAbsolute = agentDir;
+	const projectRoot = settings.projectRoot;
+	const projectMemoryInfo = projectRoot ? `\`${projectRoot}\` (detected)` : "None (not in a git project)";
+	const projectDeepagentsDir = projectRoot ? `${projectRoot}/.deepagents` : "[project-root]/.deepagents (not in a project)";
+	const template = systemPromptTemplate || DEFAULT_MEMORY_TEMPLATE;
+	return createMiddleware({
+		name: "AgentMemoryMiddleware",
+		stateSchema: AgentMemoryStateSchema,
+		beforeAgent(state) {
+			const result = {};
+			if (!("userMemory" in state)) {
+				const userPath = settings.getUserAgentMdPath(assistantId);
+				if (fs$1.existsSync(userPath)) try {
+					result.userMemory = fs$1.readFileSync(userPath, "utf-8");
+				} catch {}
+			}
+			if (!("projectMemory" in state)) {
+				const projectPath = settings.getProjectAgentMdPath();
+				if (projectPath && fs$1.existsSync(projectPath)) try {
+					result.projectMemory = fs$1.readFileSync(projectPath, "utf-8");
+				} catch {}
+			}
+			return Object.keys(result).length > 0 ? result : void 0;
+		},
+		wrapModelCall(request, handler) {
+			const userMemory = request.state?.userMemory;
+			const projectMemory = request.state?.projectMemory;
+			const baseSystemPrompt = request.systemPrompt || "";
+			const memorySection = template.replace("{user_memory}", userMemory || "(No user agent.md)").replace("{project_memory}", projectMemory || "(No project agent.md)");
+			const memoryDocs = LONGTERM_MEMORY_SYSTEM_PROMPT.replaceAll("{agent_dir_absolute}", agentDirAbsolute).replaceAll("{agent_dir_display}", agentDirDisplay).replaceAll("{project_memory_info}", projectMemoryInfo).replaceAll("{project_deepagents_dir}", projectDeepagentsDir);
+			let systemPrompt = memorySection;
+			if (baseSystemPrompt) systemPrompt += "\n\n" + baseSystemPrompt;
+			systemPrompt += "\n\n" + memoryDocs;
+			return handler({
+				...request,
+				systemPrompt
+			});
+		}
+	});
+}
+
+//#endregion
+export { BaseSandbox, CompositeBackend, FilesystemBackend, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, StateBackend, StoreBackend, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
+//# sourceMappingURL=index.js.map