deepagents 1.4.2 → 1.5.1

package/dist/index.cjs

@@ -31,8 +31,10 @@ let zod_v4 = require("zod/v4");
 let micromatch = require("micromatch");
 micromatch = __toESM(micromatch);
 let path = require("path");
-let zod_v3 = require("zod/v3");
 let _langchain_core_messages = require("@langchain/core/messages");
+let zod = require("zod");
+let yaml = require("yaml");
+yaml = __toESM(yaml);
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = __toESM(node_fs_promises);
 let node_fs = require("node:fs");
@@ -44,9 +46,6 @@ let fast_glob = require("fast-glob");
 fast_glob = __toESM(fast_glob);
 let node_os = require("node:os");
 node_os = __toESM(node_os);
-let zod = require("zod");
-let yaml = require("yaml");
-yaml = __toESM(yaml);
 
 //#region src/backends/protocol.ts
 /**
@@ -362,7 +361,7 @@ var StateBackend = class {
 	* @param limit - Maximum number of lines to read
 	* @returns Formatted file content with line numbers, or error message
 	*/
-	read(filePath, offset = 0, limit = 2e3) {
+	read(filePath, offset = 0, limit = 500) {
 		const fileData = this.getFiles()[filePath];
 		if (!fileData) return `Error: File '${filePath}' not found`;
 		return formatReadResponse(fileData, offset, limit);
@@ -619,7 +618,7 @@ function createReadFileTool(backend, options) {
 			state: (0, _langchain_langgraph.getCurrentTaskInput)(config),
 			store: config.store
 		});
-		const { file_path, offset = 0, limit = 2e3 } = input;
+		const { file_path, offset = 0, limit = 500 } = input;
 		return await resolvedBackend.read(file_path, offset, limit);
 	}, {
 		name: "read_file",
@@ -627,7 +626,7 @@ function createReadFileTool(backend, options) {
 		schema: zod_v4.z.object({
 			file_path: zod_v4.z.string().describe("Absolute path to the file to read"),
 			offset: zod_v4.z.coerce.number().optional().default(0).describe("Line offset to start reading from (0-indexed)"),
-			limit: zod_v4.z.coerce.number().optional().default(2e3).describe("Maximum number of lines to read")
+			limit: zod_v4.z.coerce.number().optional().default(500).describe("Maximum number of lines to read")
 		})
 	});
 }
@@ -883,7 +882,7 @@ const DEFAULT_SUBAGENT_PROMPT = "In order to complete the objective that the use
 const EXCLUDED_STATE_KEYS = [
 	"messages",
 	"todos",
-	"jumpTo",
+	"structuredResponse",
 	"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.";
@@ -1118,9 +1117,9 @@ function createTaskTool(options) {
 	}, {
 		name: "task",
 		description: taskDescription ? taskDescription : getTaskToolDescription(subagentDescriptions),
-		schema: zod_v3.z.object({
-			description: zod_v3.z.string().describe("The task to execute with the selected agent"),
-			subagent_type: zod_v3.z.string().describe(`Name of the agent to use. Available: ${Object.keys(subagentGraphs).join(", ")}`)
+		schema: zod_v4.z.object({
+			description: zod_v4.z.string().describe("The task to execute with the selected agent"),
+			subagent_type: zod_v4.z.string().describe(`Name of the agent to use. Available: ${Object.keys(subagentGraphs).join(", ")}`)
 		})
 	});
 }
@@ -1198,6 +1197,514 @@ function createPatchToolCallsMiddleware() {
 	});
 }
 
+//#endregion
+//#region src/middleware/memory.ts
+/**
+* Middleware for loading agent memory/context from AGENTS.md files.
+*
+* This module implements support for the AGENTS.md specification (https://agents.md/),
+* loading memory/context from configurable sources and injecting into the system prompt.
+*
+* ## Overview
+*
+* AGENTS.md files provide project-specific context and instructions to help AI agents
+* work effectively. Unlike skills (which are on-demand workflows), memory is always
+* loaded and provides persistent context.
+*
+* ## Usage
+*
+* ```typescript
+* import { createMemoryMiddleware } from "@anthropic/deepagents";
+* import { FilesystemBackend } from "@anthropic/deepagents";
+*
+* // Security: FilesystemBackend allows reading/writing from the entire filesystem.
+* // Either ensure the agent is running within a sandbox OR add human-in-the-loop (HIL)
+* // approval to file operations.
+* const backend = new FilesystemBackend({ rootDir: "/" });
+*
+* const middleware = createMemoryMiddleware({
+*   backend,
+*   sources: [
+*     "~/.deepagents/AGENTS.md",
+*     "./.deepagents/AGENTS.md",
+*   ],
+* });
+*
+* const agent = createDeepAgent({ middleware: [middleware] });
+* ```
+*
+* ## Memory Sources
+*
+* Sources are simply paths to AGENTS.md files that are loaded in order and combined.
+* Multiple sources are concatenated in order, with all content included.
+* Later sources appear after earlier ones in the combined prompt.
+*
+* ## File Format
+*
+* AGENTS.md files are standard Markdown with no required structure.
+* Common sections include:
+* - Project overview
+* - Build/test commands
+* - Code style guidelines
+* - Architecture notes
+*/
+/**
+* State schema for memory middleware.
+*/
+const MemoryStateSchema = zod.z.object({ memoryContents: zod.z.record(zod.z.string(), zod.z.string()).optional() });
+/**
+* Default system prompt template for memory.
+* Ported from Python's comprehensive memory guidelines.
+*/
+const MEMORY_SYSTEM_PROMPT = `<agent_memory>
+{memory_contents}
+</agent_memory>
+
+<memory_guidelines>
+    The above <agent_memory> was loaded in from files in your filesystem. As you learn from your interactions with the user, you can save new knowledge by calling the \`edit_file\` tool.
+
+    **Learning from feedback:**
+    - One of your MAIN PRIORITIES is to learn from your interactions with the user. These learnings can be implicit or explicit. This means that in the future, you will remember this important information.
+    - When you need to remember something, updating memory must be your FIRST, IMMEDIATE action - before responding to the user, before calling other tools, before doing anything else. Just update memory immediately.
+    - When user says something is better/worse, capture WHY and encode it as a pattern.
+    - Each correction is a chance to improve permanently - don't just fix the immediate issue, update your instructions.
+    - A great opportunity to update your memories is when the user interrupts a tool call and provides feedback. You should update your memories immediately before revising the tool call.
+    - Look for the underlying principle behind corrections, not just the specific mistake.
+    - The user might not explicitly ask you to remember something, but if they provide information that is useful for future use, you should update your memories immediately.
+
+    **Asking for information:**
+    - If you lack context to perform an action (e.g. send a Slack DM, requires a user ID/email) you should explicitly ask the user for this information.
+    - It is preferred for you to ask for information, don't assume anything that you do not know!
+    - When the user provides information that is useful for future use, you should update your memories immediately.
+
+    **When to update memories:**
+    - When the user explicitly asks you to remember something (e.g., "remember my email", "save this preference")
+    - When the user describes your role or how you should behave (e.g., "you are a web researcher", "always do X")
+    - When the user gives feedback on your work - capture what was wrong and how to improve
+    - When the user provides information required for tool use (e.g., slack channel ID, email addresses)
+    - When the user provides context useful for future tasks, such as how to use tools, or which actions to take in a particular situation
+    - When you discover new patterns or preferences (coding styles, conventions, workflows)
+
+    **When to NOT update memories:**
+    - When the information is temporary or transient (e.g., "I'm running late", "I'm on my phone right now")
+    - When the information is a one-time task request (e.g., "Find me a recipe", "What's 25 * 4?")
+    - When the information is a simple question that doesn't reveal lasting preferences (e.g., "What day is it?", "Can you explain X?")
+    - When the information is an acknowledgment or small talk (e.g., "Sounds good!", "Hello", "Thanks for that")
+    - When the information is stale or irrelevant in future conversations
+    - Never store API keys, access tokens, passwords, or any other credentials in any file, memory, or system prompt.
+    - If the user asks where to put API keys or provides an API key, do NOT echo or save it.
+
+    **Examples:**
+    Example 1 (remembering user information):
+    User: Can you connect to my google account?
+    Agent: Sure, I'll connect to your google account, what's your google account email?
+    User: john@example.com
+    Agent: Let me save this to my memory.
+    Tool Call: edit_file(...) -> remembers that the user's google account email is john@example.com
+
+    Example 2 (remembering implicit user preferences):
+    User: Can you write me an example for creating a deep agent in LangChain?
+    Agent: Sure, I'll write you an example for creating a deep agent in LangChain <example code in Python>
+    User: Can you do this in JavaScript
+    Agent: Let me save this to my memory.
+    Tool Call: edit_file(...) -> remembers that the user prefers to get LangChain code examples in JavaScript
+    Agent: Sure, here is the JavaScript example<example code in JavaScript>
+
+    Example 3 (do not remember transient information):
+    User: I'm going to play basketball tonight so I will be offline for a few hours.
+    Agent: Okay I'll add a block to your calendar.
+    Tool Call: create_calendar_event(...) -> just calls a tool, does not commit anything to memory, as it is transient information
+</memory_guidelines>`;
+/**
+* Format loaded memory contents for injection into prompt.
+* Pairs memory locations with their contents for clarity.
+*/
+function formatMemoryContents(contents, sources) {
+	if (Object.keys(contents).length === 0) return "(No memory loaded)";
+	const sections = [];
+	for (const path$4 of sources) if (contents[path$4]) sections.push(`${path$4}\n${contents[path$4]}`);
+	if (sections.length === 0) return "(No memory loaded)";
+	return sections.join("\n\n");
+}
+/**
+* Load memory content from a backend path.
+*
+* @param backend - Backend to load from.
+* @param path - Path to the AGENTS.md file.
+* @returns File content if found, null otherwise.
+*/
+async function loadMemoryFromBackend(backend, path$4) {
+	if (!backend.downloadFiles) {
+		const content = await backend.read(path$4);
+		if (content.startsWith("Error:")) return null;
+		return content;
+	}
+	const results = await backend.downloadFiles([path$4]);
+	if (results.length !== 1) throw new Error(`Expected 1 response for path ${path$4}, got ${results.length}`);
+	const response = results[0];
+	if (response.error != null) {
+		if (response.error === "file_not_found") return null;
+		throw new Error(`Failed to download ${path$4}: ${response.error}`);
+	}
+	if (response.content != null) return new TextDecoder().decode(response.content);
+	return null;
+}
+/**
+* Create middleware for loading agent memory from AGENTS.md files.
+*
+* Loads memory content from configured sources and injects into the system prompt.
+* Supports multiple sources that are combined together.
+*
+* @param options - Configuration options
+* @returns AgentMiddleware for memory loading and injection
+*
+* @example
+* ```typescript
+* const middleware = createMemoryMiddleware({
+*   backend: new FilesystemBackend({ rootDir: "/" }),
+*   sources: [
+*     "~/.deepagents/AGENTS.md",
+*     "./.deepagents/AGENTS.md",
+*   ],
+* });
+* ```
+*/
+function createMemoryMiddleware(options) {
+	const { backend, sources } = options;
+	/**
+	* Resolve backend from instance or factory.
+	*/
+	function getBackend$1(state) {
+		if (typeof backend === "function") return backend({ state });
+		return backend;
+	}
+	return (0, langchain.createMiddleware)({
+		name: "MemoryMiddleware",
+		stateSchema: MemoryStateSchema,
+		async beforeAgent(state) {
+			if ("memoryContents" in state && state.memoryContents != null) return;
+			const resolvedBackend = getBackend$1(state);
+			const contents = {};
+			for (const path$4 of sources) try {
+				const content = await loadMemoryFromBackend(resolvedBackend, path$4);
+				if (content) contents[path$4] = content;
+			} catch (error) {
+				console.debug(`Failed to load memory from ${path$4}:`, error);
+			}
+			return { memoryContents: contents };
+		},
+		wrapModelCall(request, handler) {
+			const formattedContents = formatMemoryContents(request.state?.memoryContents || {}, sources);
+			const memorySection = MEMORY_SYSTEM_PROMPT.replace("{memory_contents}", formattedContents);
+			const currentSystemPrompt = request.systemPrompt || "";
+			const newSystemPrompt = currentSystemPrompt ? `${memorySection}\n\n${currentSystemPrompt}` : memorySection;
+			return handler({
+				...request,
+				systemPrompt: newSystemPrompt
+			});
+		}
+	});
+}
+
+//#endregion
+//#region src/middleware/skills.ts
+/**
+* Backend-agnostic skills middleware for loading agent skills from any backend.
+*
+* This middleware implements Anthropic's agent skills pattern with progressive disclosure,
+* loading skills from backend storage via configurable sources.
+*
+* ## Architecture
+*
+* Skills are loaded from one or more **sources** - paths in a backend where skills are
+* organized. Sources are loaded in order, with later sources overriding earlier ones
+* when skills have the same name (last one wins). This enables layering: base -> user
+* -> project -> team skills.
+*
+* The middleware uses backend APIs exclusively (no direct filesystem access), making it
+* portable across different storage backends (filesystem, state, remote storage, etc.).
+*
+* ## Usage
+*
+* ```typescript
+* import { createSkillsMiddleware, FilesystemBackend } from "@anthropic/deepagents";
+*
+* const middleware = createSkillsMiddleware({
+*   backend: new FilesystemBackend({ rootDir: "/" }),
+*   sources: [
+*     "/skills/user/",
+*     "/skills/project/",
+*   ],
+* });
+*
+* const agent = createDeepAgent({ middleware: [middleware] });
+* ```
+*
+* Or use the `skills` parameter on createDeepAgent:
+*
+* ```typescript
+* const agent = createDeepAgent({
+*   skills: ["/skills/user/", "/skills/project/"],
+* });
+* ```
+*/
+const MAX_SKILL_FILE_SIZE = 10 * 1024 * 1024;
+const MAX_SKILL_NAME_LENGTH = 64;
+const MAX_SKILL_DESCRIPTION_LENGTH = 1024;
+/**
+* State schema for skills middleware.
+*/
+const SkillsStateSchema = zod.z.object({ skillsMetadata: zod.z.array(zod.z.object({
+	name: zod.z.string(),
+	description: zod.z.string(),
+	path: zod.z.string(),
+	license: zod.z.string().nullable().optional(),
+	compatibility: zod.z.string().nullable().optional(),
+	metadata: zod.z.record(zod.z.string(), zod.z.string()).optional(),
+	allowedTools: zod.z.array(zod.z.string()).optional()
+})).optional() });
+/**
+* Skills System Documentation prompt template.
+*/
+const SKILLS_SYSTEM_PROMPT = `
+## Skills System
+
+You have access to a skills library that provides specialized capabilities and domain knowledge.
+
+{skills_locations}
+
+**Available Skills:**
+
+{skills_list}
+
+**How to Use Skills (Progressive Disclosure):**
+
+Skills follow a **progressive disclosure** pattern - you know they exist (name + description above), but you only read the full instructions when needed:
+
+1. **Recognize when a skill applies**: Check if the user's task matches any skill's description
+2. **Read the skill's full instructions**: The skill list above shows the exact path to use with read_file
+3. **Follow the skill's instructions**: SKILL.md contains step-by-step workflows, best practices, and examples
+4. **Access supporting files**: Skills may include Python scripts, configs, or reference docs - use absolute paths
+
+**When to Use Skills:**
+- When the user's request matches a skill's domain (e.g., "research X" → web-research skill)
+- When you need specialized knowledge or structured workflows
+- When a skill provides proven patterns for complex tasks
+
+**Skills are Self-Documenting:**
+- Each SKILL.md tells you exactly what the skill does and how to use it
+- The skill list above shows the full path for each skill's SKILL.md file
+
+**Executing Skill Scripts:**
+Skills may contain Python scripts or other executable files. Always use absolute paths from the skill list.
+
+**Example Workflow:**
+
+User: "Can you research the latest developments in quantum computing?"
+
+1. Check available skills above → See "web-research" skill with its full path
+2. Read the skill using the path shown in the list
+3. Follow the skill's research workflow (search → organize → synthesize)
+4. Use any helper scripts with absolute paths
+
+Remember: Skills are tools to make you more capable and consistent. When in doubt, check if a skill exists for the task!
+`;
+/**
+* Validate skill name per Agent Skills specification.
+*/
+function validateSkillName$1(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 (!/^[a-z0-9]+(-[a-z0-9]+)*$/.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,
+		error: ""
+	};
+}
+/**
+* Parse YAML frontmatter from SKILL.md content.
+*/
+function parseSkillMetadataFromContent(content, skillPath, directoryName) {
+	if (content.length > MAX_SKILL_FILE_SIZE) {
+		console.warn(`Skipping ${skillPath}: content too large (${content.length} bytes)`);
+		return null;
+	}
+	const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+	if (!match) {
+		console.warn(`Skipping ${skillPath}: no valid YAML frontmatter found`);
+		return null;
+	}
+	const frontmatterStr = match[1];
+	let frontmatterData;
+	try {
+		frontmatterData = yaml.default.parse(frontmatterStr);
+	} catch (e) {
+		console.warn(`Invalid YAML in ${skillPath}:`, e);
+		return null;
+	}
+	if (!frontmatterData || typeof frontmatterData !== "object") {
+		console.warn(`Skipping ${skillPath}: frontmatter is not a mapping`);
+		return null;
+	}
+	const name = frontmatterData.name;
+	const description = frontmatterData.description;
+	if (!name || !description) {
+		console.warn(`Skipping ${skillPath}: missing required 'name' or 'description'`);
+		return null;
+	}
+	const validation = validateSkillName$1(String(name), directoryName);
+	if (!validation.valid) console.warn(`Skill '${name}' in ${skillPath} does not follow Agent Skills specification: ${validation.error}. Consider renaming for spec compliance.`);
+	let descriptionStr = String(description).trim();
+	if (descriptionStr.length > MAX_SKILL_DESCRIPTION_LENGTH) {
+		console.warn(`Description exceeds ${MAX_SKILL_DESCRIPTION_LENGTH} characters in ${skillPath}, truncating`);
+		descriptionStr = descriptionStr.slice(0, MAX_SKILL_DESCRIPTION_LENGTH);
+	}
+	const allowedToolsStr = frontmatterData["allowed-tools"];
+	const allowedTools = allowedToolsStr ? allowedToolsStr.split(" ") : [];
+	return {
+		name: String(name),
+		description: descriptionStr,
+		path: skillPath,
+		metadata: frontmatterData.metadata || {},
+		license: typeof frontmatterData.license === "string" ? frontmatterData.license.trim() || null : null,
+		compatibility: typeof frontmatterData.compatibility === "string" ? frontmatterData.compatibility.trim() || null : null,
+		allowedTools
+	};
+}
+/**
+* List all skills from a backend source.
+*/
+async function listSkillsFromBackend(backend, sourcePath) {
+	const skills = [];
+	const normalizedPath = sourcePath.endsWith("/") ? sourcePath : `${sourcePath}/`;
+	let fileInfos;
+	try {
+		fileInfos = await backend.lsInfo(normalizedPath);
+	} catch {
+		return [];
+	}
+	const entries = fileInfos.map((info) => ({
+		name: info.path.replace(/\/$/, "").split("/").pop() || "",
+		type: info.is_dir ? "directory" : "file"
+	}));
+	for (const entry of entries) {
+		if (entry.type !== "directory") continue;
+		const skillMdPath = `${normalizedPath}${entry.name}/SKILL.md`;
+		let content;
+		if (backend.downloadFiles) {
+			const results = await backend.downloadFiles([skillMdPath]);
+			if (results.length !== 1) continue;
+			const response = results[0];
+			if (response.error != null || response.content == null) continue;
+			content = new TextDecoder().decode(response.content);
+		} else {
+			const readResult = await backend.read(skillMdPath);
+			if (readResult.startsWith("Error:")) continue;
+			content = readResult;
+		}
+		const metadata = parseSkillMetadataFromContent(content, skillMdPath, entry.name);
+		if (metadata) skills.push(metadata);
+	}
+	return skills;
+}
+/**
+* Format skills locations for display in system prompt.
+*/
+function formatSkillsLocations(sources) {
+	if (sources.length === 0) return "**Skills Sources:** None configured";
+	const lines = ["**Skills Sources:**"];
+	for (const source of sources) lines.push(`- \`${source}\``);
+	return lines.join("\n");
+}
+/**
+* Format skills metadata for display in system prompt.
+*/
+function formatSkillsList(skills, sources) {
+	if (skills.length === 0) return `(No skills available yet. Skills can be created in ${sources.join(" or ")})`;
+	const lines = [];
+	for (const skill of skills) {
+		lines.push(`- **${skill.name}**: ${skill.description}`);
+		lines.push(`  → Read \`${skill.path}\` for full instructions`);
+	}
+	return lines.join("\n");
+}
+/**
+* Create backend-agnostic middleware for loading and exposing agent skills.
+*
+* This middleware loads skills from configurable backend sources and injects
+* skill metadata into the system prompt. It implements the progressive disclosure
+* pattern: skill names and descriptions are shown in the prompt, but the agent
+* reads full SKILL.md content only when needed.
+*
+* @param options - Configuration options
+* @returns AgentMiddleware for skills loading and injection
+*
+* @example
+* ```typescript
+* const middleware = createSkillsMiddleware({
+*   backend: new FilesystemBackend({ rootDir: "/" }),
+*   sources: ["/skills/user/", "/skills/project/"],
+* });
+* ```
+*/
+function createSkillsMiddleware(options) {
+	const { backend, sources } = options;
+	let loadedSkills = [];
+	/**
+	* Resolve backend from instance or factory.
+	*/
+	function getBackend$1(state) {
+		if (typeof backend === "function") return backend({ state });
+		return backend;
+	}
+	return (0, langchain.createMiddleware)({
+		name: "SkillsMiddleware",
+		stateSchema: SkillsStateSchema,
+		async beforeAgent(state) {
+			if (loadedSkills.length > 0) return;
+			if ("skillsMetadata" in state && state.skillsMetadata != null) {
+				loadedSkills = state.skillsMetadata;
+				return;
+			}
+			const resolvedBackend = getBackend$1(state);
+			const allSkills = /* @__PURE__ */ new Map();
+			for (const sourcePath of sources) try {
+				const skills = await listSkillsFromBackend(resolvedBackend, sourcePath);
+				for (const skill of skills) allSkills.set(skill.name, skill);
+			} catch (error) {
+				console.debug(`[BackendSkillsMiddleware] Failed to load skills from ${sourcePath}:`, error);
+			}
+			loadedSkills = Array.from(allSkills.values());
+			return { skillsMetadata: loadedSkills };
+		},
+		wrapModelCall(request, handler) {
+			const skillsMetadata = loadedSkills.length > 0 ? loadedSkills : request.state?.skillsMetadata || [];
+			const skillsLocations = formatSkillsLocations(sources);
+			const skillsList = formatSkillsList(skillsMetadata, sources);
+			const skillsSection = SKILLS_SYSTEM_PROMPT.replace("{skills_locations}", skillsLocations).replace("{skills_list}", skillsList);
+			const currentSystemPrompt = request.systemPrompt || "";
+			const newSystemPrompt = currentSystemPrompt ? `${currentSystemPrompt}\n\n${skillsSection}` : skillsSection;
+			return handler({
+				...request,
+				systemPrompt: newSystemPrompt
+			});
+		}
+	});
+}
+
 //#endregion
 //#region src/backends/store.ts
 /**
@@ -1345,7 +1852,7 @@ var StoreBackend = class {
 	* @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) {
+	async read(filePath, offset = 0, limit = 500) {
 		try {
 			return formatReadResponse(await this.readRaw(filePath), offset, limit);
 		} catch (e) {
@@ -1639,7 +2146,7 @@ var FilesystemBackend = class {
 	* @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) {
+	async read(filePath, offset = 0, limit = 500) {
 		try {
 			const resolvedPath = this.resolvePath(filePath);
 			let content;
@@ -2102,7 +2609,7 @@ var CompositeBackend = class {
 	* @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) {
+	async read(filePath, offset = 0, limit = 500) {
 		const [backend, strippedKey] = this.getBackendAndKey(filePath);
 		return await backend.read(strippedKey, offset, limit);
 	}
@@ -2223,6 +2730,7 @@ var CompositeBackend = class {
 			});
 		}
 		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++) {
@@ -2254,6 +2762,7 @@ var CompositeBackend = class {
 			});
 		}
 		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++) {
@@ -2553,7 +3062,7 @@ var BaseSandbox = class {
 	* @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) {
+	async read(filePath, offset = 0, limit = 500) {
 		const command = buildReadCommand(filePath, offset, limit);
 		const result = await this.execute(command);
 		if (result.exitCode !== 0) return `Error: File '${filePath}' not found`;
@@ -2687,7 +3196,7 @@ const BASE_PROMPT = `In order to complete the objective that the user asks of yo
 * ```
 */
 function createDeepAgent(params = {}) {
-	const { model = "claude-sonnet-4-5-20250929", tools = [], systemPrompt, middleware: customMiddleware = [], subagents = [], responseFormat, contextSchema, checkpointer, store, backend, interruptOn, name } = params;
+	const { model = "claude-sonnet-4-5-20250929", tools = [], systemPrompt, middleware: customMiddleware = [], subagents = [], responseFormat, contextSchema, checkpointer, store, backend, interruptOn, name, memory, skills } = params;
 	const finalSystemPrompt = systemPrompt ? typeof systemPrompt === "string" ? `${systemPrompt}\n\n${BASE_PROMPT}` : new langchain.SystemMessage({ content: [{
 		type: "text",
 		text: BASE_PROMPT
@@ -2696,14 +3205,20 @@ function createDeepAgent(params = {}) {
 		text: systemPrompt.content
 	}] : systemPrompt.content] }) : BASE_PROMPT;
 	const filesystemBackend = backend ? backend : (config) => new StateBackend(config);
+	const skillsMiddleware = skills != null && skills.length > 0 ? [createSkillsMiddleware({
+		backend: filesystemBackend,
+		sources: skills
+	})] : [];
 	const builtInMiddleware = [
 		(0, langchain.todoListMiddleware)(),
+		...skillsMiddleware,
 		createFilesystemMiddleware({ backend: filesystemBackend }),
 		createSubAgentMiddleware({
 			defaultModel: model,
 			defaultTools: tools,
 			defaultMiddleware: [
 				(0, langchain.todoListMiddleware)(),
+				...skillsMiddleware,
 				createFilesystemMiddleware({ backend: filesystemBackend }),
 				(0, langchain.summarizationMiddleware)({
 					model,
@@ -2723,7 +3238,11 @@ function createDeepAgent(params = {}) {
 			keep: { messages: 6 }
 		}),
 		(0, langchain.anthropicPromptCachingMiddleware)({ unsupportedModelBehavior: "ignore" }),
-		createPatchToolCallsMiddleware()
+		createPatchToolCallsMiddleware(),
+		...memory != null && memory.length > 0 ? [createMemoryMiddleware({
+			backend: filesystemBackend,
+			sources: memory
+		})] : []
 	];
 	if (interruptOn) builtInMiddleware.push((0, langchain.humanInTheLoopMiddleware)({ interruptOn }));
 	return (0, langchain.createAgent)({
@@ -2834,406 +3353,14 @@ function createSettings(options = {}) {
 }
 
 //#endregion
-//#region src/skills/loader.ts
+//#region src/middleware/agent-memory.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
-* ...
-* ```
+* Middleware for loading agent-specific long-term memory into the system prompt.
 *
-* @see https://agentskills.io/specification
-*/
-/** Maximum size for SKILL.md files (10MB) */
-const MAX_SKILL_FILE_SIZE = 10 * 1024 * 1024;
-/** Agent Skills spec constraints */
-const MAX_SKILL_NAME_LENGTH = 64;
-const MAX_SKILL_DESCRIPTION_LENGTH = 1024;
-/** Pattern for validating skill names per Agent Skills spec */
-const SKILL_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-/** Pattern for extracting YAML frontmatter */
-const FRONTMATTER_PATTERN = /^---\s*\n([\s\S]*?)\n---\s*\n/;
-/**
-* Check if a path is safely contained within base_dir.
-*
-* This prevents directory traversal attacks via symlinks or path manipulation.
-* The function resolves both paths to their canonical form (following symlinks)
-* and verifies that the target path is within the base directory.
-*
-* @param targetPath - The path to validate
-* @param baseDir - The base directory that should contain the path
-* @returns True if the path is safely within baseDir, false otherwise
-*/
-function isSafePath(targetPath, baseDir) {
-	try {
-		const resolvedPath = node_fs.default.realpathSync(targetPath);
-		const resolvedBase = node_fs.default.realpathSync(baseDir);
-		return resolvedPath.startsWith(resolvedBase + node_path.default.sep) || resolvedPath === resolvedBase;
-	} catch {
-		return false;
-	}
-}
-/**
-* Validate skill name per Agent Skills spec.
-*
-* Requirements:
-* - Max 64 characters
-* - Lowercase alphanumeric and hyphens only (a-z, 0-9, -)
-* - Cannot start or end with hyphen
-* - No consecutive hyphens
-* - Must match parent directory name
-*
-* @param name - The skill name from YAML frontmatter
-* @param directoryName - The parent directory name
-* @returns Validation result with error message if invalid
-*/
-function validateSkillName(name, directoryName) {
-	if (!name) return {
-		valid: false,
-		error: "name is required"
-	};
-	if (name.length > MAX_SKILL_NAME_LENGTH) return {
-		valid: false,
-		error: "name exceeds 64 characters"
-	};
-	if (!SKILL_NAME_PATTERN.test(name)) return {
-		valid: false,
-		error: "name must be lowercase alphanumeric with single hyphens only"
-	};
-	if (name !== directoryName) return {
-		valid: false,
-		error: `name '${name}' must match directory name '${directoryName}'`
-	};
-	return { valid: true };
-}
-/**
-* Parse YAML frontmatter from content.
-*
-* @param content - The file content
-* @returns Parsed frontmatter object, or null if parsing fails
-*/
-function parseFrontmatter(content) {
-	const match = content.match(FRONTMATTER_PATTERN);
-	if (!match) return null;
-	try {
-		const parsed = yaml.default.parse(match[1]);
-		return typeof parsed === "object" && parsed !== null ? parsed : null;
-	} catch {
-		return null;
-	}
-}
-/**
-* Parse YAML frontmatter from a SKILL.md file per Agent Skills spec.
-*
-* @param skillMdPath - Path to the SKILL.md file
-* @param source - Source of the skill ('user' or 'project')
-* @returns SkillMetadata with all fields, or null if parsing fails
-*/
-function parseSkillMetadata(skillMdPath, source) {
-	try {
-		const stats = node_fs.default.statSync(skillMdPath);
-		if (stats.size > MAX_SKILL_FILE_SIZE) {
-			console.warn(`Skipping ${skillMdPath}: file too large (${stats.size} bytes)`);
-			return null;
-		}
-		const frontmatter = parseFrontmatter(node_fs.default.readFileSync(skillMdPath, "utf-8"));
-		if (!frontmatter) {
-			console.warn(`Skipping ${skillMdPath}: no valid YAML frontmatter found`);
-			return null;
-		}
-		const name = frontmatter.name;
-		const description = frontmatter.description;
-		if (!name || !description) {
-			console.warn(`Skipping ${skillMdPath}: missing required 'name' or 'description'`);
-			return null;
-		}
-		const directoryName = node_path.default.basename(node_path.default.dirname(skillMdPath));
-		const validation = validateSkillName(String(name), directoryName);
-		if (!validation.valid) console.warn(`Skill '${name}' in ${skillMdPath} does not follow Agent Skills spec: ${validation.error}. Consider renaming to be spec-compliant.`);
-		let descriptionStr = String(description);
-		if (descriptionStr.length > MAX_SKILL_DESCRIPTION_LENGTH) {
-			console.warn(`Description exceeds ${MAX_SKILL_DESCRIPTION_LENGTH} chars in ${skillMdPath}, truncating`);
-			descriptionStr = descriptionStr.slice(0, MAX_SKILL_DESCRIPTION_LENGTH);
-		}
-		return {
-			name: String(name),
-			description: descriptionStr,
-			path: skillMdPath,
-			source,
-			license: frontmatter.license ? String(frontmatter.license) : void 0,
-			compatibility: frontmatter.compatibility ? String(frontmatter.compatibility) : void 0,
-			metadata: frontmatter.metadata && typeof frontmatter.metadata === "object" ? frontmatter.metadata : void 0,
-			allowedTools: frontmatter["allowed-tools"] ? String(frontmatter["allowed-tools"]) : void 0
-		};
-	} catch (error) {
-		console.warn(`Error reading ${skillMdPath}: ${error}`);
-		return null;
-	}
-}
-/**
-* List all skills from a single skills directory (internal helper).
-*
-* Scans the skills directory for subdirectories containing SKILL.md files,
-* parses YAML frontmatter, and returns skill metadata.
-*
-* Skills are organized as:
-* ```
-* skills/
-* ├── skill-name/
-* │   ├── SKILL.md        # Required: instructions with YAML frontmatter
-* │   ├── script.py       # Optional: supporting files
-* │   └── config.json     # Optional: supporting files
-* ```
-*
-* @param skillsDir - Path to the skills directory
-* @param source - Source of the skills ('user' or 'project')
-* @returns List of skill metadata
-*/
-function listSkillsFromDir(skillsDir, source) {
-	const expandedDir = skillsDir.startsWith("~") ? node_path.default.join(process.env.HOME || process.env.USERPROFILE || "", skillsDir.slice(1)) : skillsDir;
-	if (!node_fs.default.existsSync(expandedDir)) return [];
-	let resolvedBase;
-	try {
-		resolvedBase = node_fs.default.realpathSync(expandedDir);
-	} catch {
-		return [];
-	}
-	const skills = [];
-	let entries;
-	try {
-		entries = node_fs.default.readdirSync(resolvedBase, { withFileTypes: true });
-	} catch {
-		return [];
-	}
-	for (const entry of entries) {
-		const skillDir = node_path.default.join(resolvedBase, entry.name);
-		if (!isSafePath(skillDir, resolvedBase)) continue;
-		if (!entry.isDirectory()) continue;
-		const skillMdPath = node_path.default.join(skillDir, "SKILL.md");
-		if (!node_fs.default.existsSync(skillMdPath)) continue;
-		if (!isSafePath(skillMdPath, resolvedBase)) continue;
-		const metadata = parseSkillMetadata(skillMdPath, source);
-		if (metadata) skills.push(metadata);
-	}
-	return skills;
-}
-/**
-* List skills from user and/or project directories.
-*
-* When both directories are provided, project skills with the same name as
-* user skills will override them.
-*
-* @param options - Options specifying which directories to search
-* @returns Merged list of skill metadata from both sources, with project skills
-*          taking precedence over user skills when names conflict
-*/
-function listSkills(options) {
-	const allSkills = /* @__PURE__ */ new Map();
-	if (options.userSkillsDir) {
-		const userSkills = listSkillsFromDir(options.userSkillsDir, "user");
-		for (const skill of userSkills) allSkills.set(skill.name, skill);
-	}
-	if (options.projectSkillsDir) {
-		const projectSkills = listSkillsFromDir(options.projectSkillsDir, "project");
-		for (const skill of projectSkills) allSkills.set(skill.name, skill);
-	}
-	return Array.from(allSkills.values());
-}
-
-//#endregion
-//#region src/middleware/skills.ts
-/**
-* Middleware for loading and exposing agent skills to the system prompt.
-*
-* This middleware implements Anthropic's "Agent Skills" pattern with progressive disclosure:
-* 1. Parse YAML frontmatter from SKILL.md files at session start
-* 2. Inject skills metadata (name + description) into system prompt
-* 3. Agent reads full SKILL.md content when relevant to a task
-*
-* Skills directory structure (per-agent + project):
-* User-level: ~/.deepagents/{AGENT_NAME}/skills/
-* Project-level: {PROJECT_ROOT}/.deepagents/skills/
-*
-* @example
-* ```
-* ~/.deepagents/{AGENT_NAME}/skills/
-* ├── web-research/
-* │   ├── SKILL.md        # Required: YAML frontmatter + instructions
-* │   └── helper.py       # Optional: supporting files
-* ├── code-review/
-* │   ├── SKILL.md
-* │   └── checklist.md
-*
-* .deepagents/skills/
-* ├── project-specific/
-* │   └── SKILL.md        # Project-specific skills
-* ```
-*/
-/**
-* State schema for skills middleware.
-*/
-const SkillsStateSchema = zod.z.object({ skillsMetadata: zod.z.array(zod.z.object({
-	name: zod.z.string(),
-	description: zod.z.string(),
-	path: zod.z.string(),
-	source: zod.z.enum(["user", "project"]),
-	license: zod.z.string().optional(),
-	compatibility: zod.z.string().optional(),
-	metadata: zod.z.record(zod.z.string(), zod.z.string()).optional(),
-	allowedTools: zod.z.string().optional()
-})).optional() });
-/**
-* Skills System Documentation prompt template.
-*/
-const SKILLS_SYSTEM_PROMPT = `
-
-## Skills System
-
-You have access to a skills library that provides specialized capabilities and domain knowledge.
-
-{skills_locations}
-
-**Available Skills:**
-
-{skills_list}
-
-**How to Use Skills (Progressive Disclosure):**
-
-Skills follow a **progressive disclosure** pattern - you know they exist (name + description above), but you only read the full instructions when needed:
-
-1. **Recognize when a skill applies**: Check if the user's task matches any skill's description
-2. **Read the skill's full instructions**: The skill list above shows the exact path to use with read_file
-3. **Follow the skill's instructions**: SKILL.md contains step-by-step workflows, best practices, and examples
-4. **Access supporting files**: Skills may include Python scripts, configs, or reference docs - use absolute paths
-
-**When to Use Skills:**
-- When the user's request matches a skill's domain (e.g., "research X" → web-research skill)
-- When you need specialized knowledge or structured workflows
-- When a skill provides proven patterns for complex tasks
-
-**Skills are Self-Documenting:**
-- Each SKILL.md tells you exactly what the skill does and how to use it
-- The skill list above shows the full path for each skill's SKILL.md file
-
-**Executing Skill Scripts:**
-Skills may contain Python scripts or other executable files. Always use absolute paths from the skill list.
-
-**Example Workflow:**
-
-User: "Can you research the latest developments in quantum computing?"
-
-1. Check available skills above → See "web-research" skill with its full path
-2. Read the skill using the path shown in the list
-3. Follow the skill's research workflow (search → organize → synthesize)
-4. Use any helper scripts with absolute paths
-
-Remember: Skills are tools to make you more capable and consistent. When in doubt, check if a skill exists for the task!
-`;
-/**
-* Format skills locations for display in system prompt.
-*/
-function formatSkillsLocations(userSkillsDisplay, projectSkillsDir) {
-	const locations = [`**User Skills**: \`${userSkillsDisplay}\``];
-	if (projectSkillsDir) locations.push(`**Project Skills**: \`${projectSkillsDir}\` (overrides user skills)`);
-	return locations.join("\n");
-}
-/**
-* Format skills metadata for display in system prompt.
-*/
-function formatSkillsList(skills, userSkillsDisplay, projectSkillsDir) {
-	if (skills.length === 0) {
-		const locations = [userSkillsDisplay];
-		if (projectSkillsDir) locations.push(projectSkillsDir);
-		return `(No skills available yet. You can create skills in ${locations.join(" or ")})`;
-	}
-	const userSkills = skills.filter((s) => s.source === "user");
-	const projectSkills = skills.filter((s) => s.source === "project");
-	const lines = [];
-	if (userSkills.length > 0) {
-		lines.push("**User Skills:**");
-		for (const skill of userSkills) {
-			lines.push(`- **${skill.name}**: ${skill.description}`);
-			lines.push(`  → Read \`${skill.path}\` for full instructions`);
-		}
-		lines.push("");
-	}
-	if (projectSkills.length > 0) {
-		lines.push("**Project Skills:**");
-		for (const skill of projectSkills) {
-			lines.push(`- **${skill.name}**: ${skill.description}`);
-			lines.push(`  → Read \`${skill.path}\` for full instructions`);
-		}
-	}
-	return lines.join("\n");
-}
-/**
-* Create middleware for loading and exposing agent skills.
-*
-* This middleware implements Anthropic's agent skills pattern:
-* - Loads skills metadata (name, description) from YAML frontmatter at session start
-* - Injects skills list into system prompt for discoverability
-* - Agent reads full SKILL.md content when a skill is relevant (progressive disclosure)
-*
-* Supports both user-level and project-level skills:
-* - User skills: ~/.deepagents/{AGENT_NAME}/skills/
-* - Project skills: {PROJECT_ROOT}/.deepagents/skills/
-* - Project skills override user skills with the same name
-*
-* @param options - Configuration options
-* @returns AgentMiddleware for skills loading and injection
-*/
-function createSkillsMiddleware(options) {
-	const { skillsDir, assistantId, projectSkillsDir } = options;
-	const userSkillsDisplay = `~/.deepagents/${assistantId}/skills`;
-	return (0, langchain.createMiddleware)({
-		name: "SkillsMiddleware",
-		stateSchema: SkillsStateSchema,
-		beforeAgent() {
-			return { skillsMetadata: listSkills({
-				userSkillsDir: skillsDir,
-				projectSkillsDir
-			}) };
-		},
-		wrapModelCall(request, handler) {
-			const skillsMetadata = request.state?.skillsMetadata || [];
-			const skillsLocations = formatSkillsLocations(userSkillsDisplay, projectSkillsDir);
-			const skillsList = formatSkillsList(skillsMetadata, userSkillsDisplay, projectSkillsDir);
-			const skillsSection = SKILLS_SYSTEM_PROMPT.replace("{skills_locations}", skillsLocations).replace("{skills_list}", skillsList);
-			const currentSystemPrompt = request.systemPrompt || "";
-			const newSystemPrompt = currentSystemPrompt ? `${currentSystemPrompt}\n\n${skillsSection}` : skillsSection;
-			return handler({
-				...request,
-				systemPrompt: newSystemPrompt
-			});
-		}
-	});
-}
-
-//#endregion
-//#region src/middleware/agent-memory.ts
-/**
-* Middleware for loading agent-specific long-term memory into the system prompt.
-*
-* This middleware loads the agent's long-term memory from agent.md files
-* and injects it into the system prompt. Memory is loaded from:
-* - User memory: ~/.deepagents/{agent_name}/agent.md
-* - Project memory: {project_root}/.deepagents/agent.md
+* 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.
@@ -3425,6 +3552,229 @@ function createAgentMemoryMiddleware(options) {
 	});
 }
 
+//#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$1 = 10 * 1024 * 1024;
+/** Agent Skills spec constraints */
+const MAX_SKILL_NAME_LENGTH$1 = 64;
+const MAX_SKILL_DESCRIPTION_LENGTH$1 = 1024;
+/** Pattern for validating skill names per Agent Skills spec */
+const SKILL_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/** Pattern for extracting YAML frontmatter */
+const FRONTMATTER_PATTERN = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+/**
+* Check if a path is safely contained within base_dir.
+*
+* This prevents directory traversal attacks via symlinks or path manipulation.
+* The function resolves both paths to their canonical form (following symlinks)
+* and verifies that the target path is within the base directory.
+*
+* @param targetPath - The path to validate
+* @param baseDir - The base directory that should contain the path
+* @returns True if the path is safely within baseDir, false otherwise
+*/
+function isSafePath(targetPath, baseDir) {
+	try {
+		const resolvedPath = node_fs.default.realpathSync(targetPath);
+		const resolvedBase = node_fs.default.realpathSync(baseDir);
+		return resolvedPath.startsWith(resolvedBase + node_path.default.sep) || resolvedPath === resolvedBase;
+	} catch {
+		return false;
+	}
+}
+/**
+* Validate skill name per Agent Skills spec.
+*
+* Requirements:
+* - Max 64 characters
+* - Lowercase alphanumeric and hyphens only (a-z, 0-9, -)
+* - Cannot start or end with hyphen
+* - No consecutive hyphens
+* - Must match parent directory name
+*
+* @param name - The skill name from YAML frontmatter
+* @param directoryName - The parent directory name
+* @returns Validation result with error message if invalid
+*/
+function validateSkillName(name, directoryName) {
+	if (!name) return {
+		valid: false,
+		error: "name is required"
+	};
+	if (name.length > MAX_SKILL_NAME_LENGTH$1) return {
+		valid: false,
+		error: "name exceeds 64 characters"
+	};
+	if (!SKILL_NAME_PATTERN.test(name)) return {
+		valid: false,
+		error: "name must be lowercase alphanumeric with single hyphens only"
+	};
+	if (name !== directoryName) return {
+		valid: false,
+		error: `name '${name}' must match directory name '${directoryName}'`
+	};
+	return { valid: true };
+}
+/**
+* Parse YAML frontmatter from content.
+*
+* @param content - The file content
+* @returns Parsed frontmatter object, or null if parsing fails
+*/
+function parseFrontmatter(content) {
+	const match = content.match(FRONTMATTER_PATTERN);
+	if (!match) return null;
+	try {
+		const parsed = yaml.default.parse(match[1]);
+		return typeof parsed === "object" && parsed !== null ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Parse YAML frontmatter from a SKILL.md file per Agent Skills spec.
+*
+* @param skillMdPath - Path to the SKILL.md file
+* @param source - Source of the skill ('user' or 'project')
+* @returns SkillMetadata with all fields, or null if parsing fails
+*/
+function parseSkillMetadata(skillMdPath, source) {
+	try {
+		const stats = node_fs.default.statSync(skillMdPath);
+		if (stats.size > MAX_SKILL_FILE_SIZE$1) {
+			console.warn(`Skipping ${skillMdPath}: file too large (${stats.size} bytes)`);
+			return null;
+		}
+		const frontmatter = parseFrontmatter(node_fs.default.readFileSync(skillMdPath, "utf-8"));
+		if (!frontmatter) {
+			console.warn(`Skipping ${skillMdPath}: no valid YAML frontmatter found`);
+			return null;
+		}
+		const name = frontmatter.name;
+		const description = frontmatter.description;
+		if (!name || !description) {
+			console.warn(`Skipping ${skillMdPath}: missing required 'name' or 'description'`);
+			return null;
+		}
+		const directoryName = node_path.default.basename(node_path.default.dirname(skillMdPath));
+		const validation = validateSkillName(String(name), directoryName);
+		if (!validation.valid) console.warn(`Skill '${name}' in ${skillMdPath} does not follow Agent Skills spec: ${validation.error}. Consider renaming to be spec-compliant.`);
+		let descriptionStr = String(description);
+		if (descriptionStr.length > MAX_SKILL_DESCRIPTION_LENGTH$1) {
+			console.warn(`Description exceeds ${MAX_SKILL_DESCRIPTION_LENGTH$1} chars in ${skillMdPath}, truncating`);
+			descriptionStr = descriptionStr.slice(0, MAX_SKILL_DESCRIPTION_LENGTH$1);
+		}
+		return {
+			name: String(name),
+			description: descriptionStr,
+			path: skillMdPath,
+			source,
+			license: frontmatter.license ? String(frontmatter.license) : void 0,
+			compatibility: frontmatter.compatibility ? String(frontmatter.compatibility) : void 0,
+			metadata: frontmatter.metadata && typeof frontmatter.metadata === "object" ? frontmatter.metadata : void 0,
+			allowedTools: frontmatter["allowed-tools"] ? String(frontmatter["allowed-tools"]) : void 0
+		};
+	} catch (error) {
+		console.warn(`Error reading ${skillMdPath}: ${error}`);
+		return null;
+	}
+}
+/**
+* List all skills from a single skills directory (internal helper).
+*
+* Scans the skills directory for subdirectories containing SKILL.md files,
+* parses YAML frontmatter, and returns skill metadata.
+*
+* Skills are organized as:
+* ```
+* skills/
+* ├── skill-name/
+* │   ├── SKILL.md        # Required: instructions with YAML frontmatter
+* │   ├── script.py       # Optional: supporting files
+* │   └── config.json     # Optional: supporting files
+* ```
+*
+* @param skillsDir - Path to the skills directory
+* @param source - Source of the skills ('user' or 'project')
+* @returns List of skill metadata
+*/
+function listSkillsFromDir(skillsDir, source) {
+	const expandedDir = skillsDir.startsWith("~") ? node_path.default.join(process.env.HOME || process.env.USERPROFILE || "", skillsDir.slice(1)) : skillsDir;
+	if (!node_fs.default.existsSync(expandedDir)) return [];
+	let resolvedBase;
+	try {
+		resolvedBase = node_fs.default.realpathSync(expandedDir);
+	} catch {
+		return [];
+	}
+	const skills = [];
+	let entries;
+	try {
+		entries = node_fs.default.readdirSync(resolvedBase, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	for (const entry of entries) {
+		const skillDir = node_path.default.join(resolvedBase, entry.name);
+		if (!isSafePath(skillDir, resolvedBase)) continue;
+		if (!entry.isDirectory()) continue;
+		const skillMdPath = node_path.default.join(skillDir, "SKILL.md");
+		if (!node_fs.default.existsSync(skillMdPath)) continue;
+		if (!isSafePath(skillMdPath, resolvedBase)) continue;
+		const metadata = parseSkillMetadata(skillMdPath, source);
+		if (metadata) skills.push(metadata);
+	}
+	return skills;
+}
+/**
+* List skills from user and/or project directories.
+*
+* When both directories are provided, project skills with the same name as
+* user skills will override them.
+*
+* @param options - Options specifying which directories to search
+* @returns Merged list of skill metadata from both sources, with project skills
+*          taking precedence over user skills when names conflict
+*/
+function listSkills(options) {
+	const allSkills = /* @__PURE__ */ new Map();
+	if (options.userSkillsDir) {
+		const userSkills = listSkillsFromDir(options.userSkillsDir, "user");
+		for (const skill of userSkills) allSkills.set(skill.name, skill);
+	}
+	if (options.projectSkillsDir) {
+		const projectSkills = listSkillsFromDir(options.projectSkillsDir, "project");
+		for (const skill of projectSkills) allSkills.set(skill.name, skill);
+	}
+	return Array.from(allSkills.values());
+}
+
 //#endregion
 exports.BaseSandbox = BaseSandbox;
 exports.CompositeBackend = CompositeBackend;
@@ -3437,6 +3787,7 @@ exports.StoreBackend = StoreBackend;
 exports.createAgentMemoryMiddleware = createAgentMemoryMiddleware;
 exports.createDeepAgent = createDeepAgent;
 exports.createFilesystemMiddleware = createFilesystemMiddleware;
+exports.createMemoryMiddleware = createMemoryMiddleware;
 exports.createPatchToolCallsMiddleware = createPatchToolCallsMiddleware;
 exports.createSettings = createSettings;
 exports.createSkillsMiddleware = createSkillsMiddleware;