deepagents 1.10.2 → 1.10.5

package/dist/src-DybKvM4T.js

@@ -0,0 +1,1402 @@
+import { G as getMimeType, K as isTextMimeType, R as SandboxError, W as checkEmptyContent, q as performStringReplacement } from "./langsmith-wdF8zG42.js";
+import { createMiddleware } from "langchain";
+import micromatch from "micromatch";
+import { z } from "zod";
+import yaml from "yaml";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import fs$1 from "node:fs/promises";
+import cp, { spawn } from "node:child_process";
+import fg from "fast-glob";
+//#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.existsSync(gitDir)) return current;
+		current = path.dirname(current);
+	}
+	const rootGitDir = path.join(current, ".git");
+	if (fs.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.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.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.mkdirSync(skillsDir, { recursive: true });
+			return skillsDir;
+		},
+		ensureProjectDeepagentsDir() {
+			if (!projectRoot) return null;
+			const deepagentsDir = path.join(projectRoot, ".deepagents");
+			fs.mkdirSync(deepagentsDir, { recursive: true });
+			return deepagentsDir;
+		}
+	};
+}
+//#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
+*
+* @deprecated Use `createMemoryMiddleware` from `./memory.js` instead.
+* This middleware uses direct filesystem access (Node.js fs module) which is not
+* portable across backends. The `createMemoryMiddleware` function uses the
+* `BackendProtocol` abstraction and follows the AGENTS.md specification.
+*
+* Migration example:
+* ```typescript
+* // Before (deprecated):
+* import { createAgentMemoryMiddleware } from "./agent-memory.js";
+* const middleware = createAgentMemoryMiddleware({ settings, assistantId });
+*
+* // After (recommended):
+* import { createMemoryMiddleware } from "./memory.js";
+* import { FilesystemBackend } from "../backends/filesystem.js";
+*
+* const middleware = createMemoryMiddleware({
+*   backend: new FilesystemBackend({ rootDir: "/" }),
+*   sources: [
+*     `~/.deepagents/${assistantId}/AGENTS.md`,
+*     `${projectRoot}/.deepagents/AGENTS.md`,
+*   ],
+* });
+* ```
+*/
+/**
+* State schema for agent memory middleware.
+*/
+const AgentMemoryStateSchema = z.object({
+	/** Personal preferences from ~/.deepagents/{agent}/ (applies everywhere) */
+	userMemory: z.string().optional(),
+	/** Project-specific context (loaded from project root) */
+	projectMemory: z.string().optional()
+});
+/**
+* Default template for memory injection.
+*/
+const DEFAULT_MEMORY_TEMPLATE = `<user_memory>
+{user_memory}
+</user_memory>
+
+<project_memory>
+{project_memory}
+</project_memory>`;
+/**
+* Long-term Memory Documentation system prompt.
+*/
+const LONGTERM_MEMORY_SYSTEM_PROMPT = `
+
+## Long-term Memory
+
+Your long-term memory is stored in files on the filesystem and persists across sessions.
+
+**User Memory Location**: \`{agent_dir_absolute}\` (displays as \`{agent_dir_display}\`)
+**Project Memory Location**: {project_memory_info}
+
+Your system prompt is loaded from TWO sources at startup:
+1. **User agent.md**: \`{agent_dir_absolute}/agent.md\` - Your personal preferences across all projects
+2. **Project agent.md**: Loaded from project root if available - Project-specific instructions
+
+Project-specific agent.md is loaded from these locations (both combined if both exist):
+- \`[project-root]/.deepagents/agent.md\` (preferred)
+- \`[project-root]/agent.md\` (fallback, but also included if both exist)
+
+**When to CHECK/READ memories (CRITICAL - do this FIRST):**
+- **At the start of ANY new session**: Check both user and project memories
+  - User: \`ls {agent_dir_absolute}\`
+  - Project: \`ls {project_deepagents_dir}\` (if in a project)
+- **BEFORE answering questions**: If asked "what do you know about X?" or "how do I do Y?", check project memories FIRST, then user
+- **When user asks you to do something**: Check if you have project-specific guides or examples
+- **When user references past work**: Search project memory files for related context
+
+**Memory-first response pattern:**
+1. User asks a question → Check project directory first: \`ls {project_deepagents_dir}\`
+2. If relevant files exist → Read them with \`read_file '{project_deepagents_dir}/[filename]'\`
+3. Check user memory if needed → \`ls {agent_dir_absolute}\`
+4. Base your answer on saved knowledge supplemented by general knowledge
+
+**When to update memories:**
+- **IMMEDIATELY when the user describes your role or how you should behave**
+- **IMMEDIATELY when the user gives feedback on your work** - Update memories to capture what was wrong and how to do it better
+- When the user explicitly asks you to remember something
+- When patterns or preferences emerge (coding styles, conventions, workflows)
+- After significant work where context would help in future sessions
+
+**Learning from feedback:**
+- When user says something is better/worse, capture WHY and encode it as a pattern
+- Each correction is a chance to improve permanently - don't just fix the immediate issue, update your instructions
+- When user says "you should remember X" or "be careful about Y", treat this as HIGH PRIORITY - update memories IMMEDIATELY
+- Look for the underlying principle behind corrections, not just the specific mistake
+
+## Deciding Where to Store Memory
+
+When writing or updating agent memory, decide whether each fact, configuration, or behavior belongs in:
+
+### User Agent File: \`{agent_dir_absolute}/agent.md\`
+→ Describes the agent's **personality, style, and universal behavior** across all projects.
+
+**Store here:**
+- Your general tone and communication style
+- Universal coding preferences (formatting, comment style, etc.)
+- General workflows and methodologies you follow
+- Tool usage patterns that apply everywhere
+- Personal preferences that don't change per-project
+
+**Examples:**
+- "Be concise and direct in responses"
+- "Always use type hints in Python"
+- "Prefer functional programming patterns"
+
+### Project Agent File: \`{project_deepagents_dir}/agent.md\`
+→ Describes **how this specific project works** and **how the agent should behave here only.**
+
+**Store here:**
+- Project-specific architecture and design patterns
+- Coding conventions specific to this codebase
+- Project structure and organization
+- Testing strategies for this project
+- Deployment processes and workflows
+- Team conventions and guidelines
+
+**Examples:**
+- "This project uses FastAPI with SQLAlchemy"
+- "Tests go in tests/ directory mirroring src/ structure"
+- "All API changes require updating OpenAPI spec"
+
+### Project Memory Files: \`{project_deepagents_dir}/*.md\`
+→ Use for **project-specific reference information** and structured notes.
+
+**Store here:**
+- API design documentation
+- Architecture decisions and rationale
+- Deployment procedures
+- Common debugging patterns
+- Onboarding information
+
+**Examples:**
+- \`{project_deepagents_dir}/api-design.md\` - REST API patterns used
+- \`{project_deepagents_dir}/architecture.md\` - System architecture overview
+- \`{project_deepagents_dir}/deployment.md\` - How to deploy this project
+
+### File Operations:
+
+**User memory:**
+\`\`\`
+ls {agent_dir_absolute}                              # List user memory files
+read_file '{agent_dir_absolute}/agent.md'            # Read user preferences
+edit_file '{agent_dir_absolute}/agent.md' ...        # Update user preferences
+\`\`\`
+
+**Project memory (preferred for project-specific information):**
+\`\`\`
+ls {project_deepagents_dir}                          # List project memory files
+read_file '{project_deepagents_dir}/agent.md'        # Read project instructions
+edit_file '{project_deepagents_dir}/agent.md' ...    # Update project instructions
+write_file '{project_deepagents_dir}/agent.md' ...  # Create project memory file
+\`\`\`
+
+**Important**:
+- Project memory files are stored in \`.deepagents/\` inside the project root
+- Always use absolute paths for file operations
+- Check project memories BEFORE user when answering project-specific questions`;
+/**
+* Create middleware for loading agent-specific long-term memory.
+*
+* This middleware loads the agent's long-term memory from a file (agent.md)
+* and injects it into the system prompt. The memory is loaded once at the
+* start of the conversation and stored in state.
+*
+* @param options - Configuration options
+* @returns AgentMiddleware for memory loading and injection
+*
+* @deprecated Use `createMemoryMiddleware` from `./memory.js` instead.
+* This function uses direct filesystem access which limits portability.
+*/
+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.existsSync(userPath)) try {
+					result.userMemory = fs.readFileSync(userPath, "utf-8");
+				} catch {}
+			}
+			if (!("projectMemory" in state)) {
+				const projectPath = settings.getProjectAgentMdPath();
+				if (projectPath && fs.existsSync(projectPath)) try {
+					result.projectMemory = fs.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
+			});
+		}
+	});
+}
+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.realpathSync(targetPath);
+		const resolvedBase = fs.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 > 64) 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.statSync(skillMdPath);
+		if (stats.size > 10485760) {
+			console.warn(`Skipping ${skillMdPath}: file too large (${stats.size} bytes)`);
+			return null;
+		}
+		const frontmatter = parseFrontmatter(fs.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 > 1024) {
+			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.existsSync(expandedDir)) return [];
+	let resolvedBase;
+	try {
+		resolvedBase = fs.realpathSync(expandedDir);
+	} catch {
+		return [];
+	}
+	const skills = [];
+	let entries;
+	try {
+		entries = fs.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.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/backends/filesystem.ts
+/**
+* FilesystemBackend: Read and write files directly from the filesystem.
+*
+* Security and search upgrades:
+* - Secure path resolution with root containment when in virtual_mode (sandboxed to cwd)
+* - Prevent symlink-following on file I/O using O_NOFOLLOW when available
+* - Ripgrep-powered grep with literal (fixed-string) search, plus substring fallback
+*   and optional glob include filtering, while preserving virtual path behavior
+*/
+const SUPPORTS_NOFOLLOW = fs.constants.O_NOFOLLOW !== void 0;
+/**
+* Backend that reads and writes files directly from the filesystem.
+*
+* Files are accessed using their actual filesystem paths. Relative paths are
+* resolved relative to the current working directory. Content is read/written
+* as plain text, and metadata (timestamps) are derived from filesystem stats.
+*/
+var FilesystemBackend = class {
+	cwd;
+	virtualMode;
+	maxFileSizeBytes;
+	constructor(options = {}) {
+		const { rootDir, virtualMode = false, maxFileSizeMb = 10 } = options;
+		this.cwd = rootDir ? path.resolve(rootDir) : process.cwd();
+		this.virtualMode = virtualMode;
+		this.maxFileSizeBytes = maxFileSizeMb * 1024 * 1024;
+	}
+	/**
+	* Resolve a file path with security checks.
+	*
+	* When virtualMode=true, treat incoming paths as virtual absolute paths under
+	* this.cwd, disallow traversal (.., ~) and ensure resolved path stays within root.
+	* When virtualMode=false, preserve legacy behavior: absolute paths are allowed
+	* as-is; relative paths resolve under cwd.
+	*
+	* @param key - File path (absolute, relative, or virtual when virtualMode=true)
+	* @returns Resolved absolute path string
+	* @throws Error if path traversal detected or path outside root
+	*/
+	resolvePath(key) {
+		if (this.virtualMode) {
+			const vpath = key.startsWith("/") ? key : "/" + key;
+			if (vpath.includes("..") || vpath.startsWith("~")) throw new Error("Path traversal not allowed");
+			const full = path.resolve(this.cwd, vpath.substring(1));
+			const relative = path.relative(this.cwd, full);
+			if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Path: ${full} outside root directory: ${this.cwd}`);
+			return full;
+		}
+		if (path.isAbsolute(key)) return key;
+		return path.resolve(this.cwd, key);
+	}
+	/**
+	* List files and directories in the specified directory (non-recursive).
+	*
+	* @param dirPath - Absolute directory path to list files from
+	* @returns List of FileInfo objects for files and directories directly in the directory.
+	*          Directories have a trailing / in their path and is_dir=true.
+	*/
+	async ls(dirPath) {
+		try {
+			const resolvedPath = this.resolvePath(dirPath);
+			if (!(await fs$1.stat(resolvedPath)).isDirectory()) return { files: [] };
+			const entries = await fs$1.readdir(resolvedPath, { withFileTypes: true });
+			const results = [];
+			const cwdStr = this.cwd.endsWith(path.sep) ? this.cwd : this.cwd + path.sep;
+			for (const entry of entries) {
+				const fullPath = path.join(resolvedPath, entry.name);
+				try {
+					const entryStat = await fs$1.stat(fullPath);
+					const isFile = entryStat.isFile();
+					const isDir = entryStat.isDirectory();
+					if (!this.virtualMode) {
+						if (isFile) results.push({
+							path: fullPath,
+							is_dir: false,
+							size: entryStat.size,
+							modified_at: entryStat.mtime.toISOString()
+						});
+						else if (isDir) results.push({
+							path: fullPath + path.sep,
+							is_dir: true,
+							size: 0,
+							modified_at: entryStat.mtime.toISOString()
+						});
+					} else {
+						let relativePath;
+						if (fullPath.startsWith(cwdStr)) relativePath = fullPath.substring(cwdStr.length);
+						else if (fullPath.startsWith(this.cwd)) relativePath = fullPath.substring(this.cwd.length).replace(/^[/\\]/, "");
+						else relativePath = fullPath;
+						relativePath = relativePath.split(path.sep).join("/");
+						const virtPath = "/" + relativePath;
+						if (isFile) results.push({
+							path: virtPath,
+							is_dir: false,
+							size: entryStat.size,
+							modified_at: entryStat.mtime.toISOString()
+						});
+						else if (isDir) results.push({
+							path: virtPath + "/",
+							is_dir: true,
+							size: 0,
+							modified_at: entryStat.mtime.toISOString()
+						});
+					}
+				} catch {
+					continue;
+				}
+			}
+			results.sort((a, b) => a.path.localeCompare(b.path));
+			return { files: results };
+		} catch {
+			return { files: [] };
+		}
+	}
+	/**
+	* Read file content with line numbers.
+	*
+	* @param filePath - Absolute or relative file path
+	* @param offset - Line offset to start reading from (0-indexed)
+	* @param limit - Maximum number of lines to read
+	* @returns Formatted file content with line numbers, or error message
+	*/
+	async read(filePath, offset = 0, limit = 500) {
+		try {
+			const resolvedPath = this.resolvePath(filePath);
+			const mimeType = getMimeType(filePath);
+			const isBinary = !isTextMimeType(mimeType);
+			let content;
+			if (SUPPORTS_NOFOLLOW) {
+				if (!(await fs$1.stat(resolvedPath)).isFile()) return { error: `File '${filePath}' not found` };
+				const fd = await fs$1.open(resolvedPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+				try {
+					if (isBinary) {
+						const buffer = await fd.readFile();
+						return {
+							content: new Uint8Array(buffer),
+							mimeType
+						};
+					}
+					content = await fd.readFile({ encoding: "utf-8" });
+				} finally {
+					await fd.close();
+				}
+			} else {
+				const stat = await fs$1.lstat(resolvedPath);
+				if (stat.isSymbolicLink()) return { error: `Symlinks are not allowed: ${filePath}` };
+				if (!stat.isFile()) return { error: `File '${filePath}' not found` };
+				if (isBinary) {
+					const buffer = await fs$1.readFile(resolvedPath);
+					return {
+						content: new Uint8Array(buffer),
+						mimeType
+					};
+				}
+				content = await fs$1.readFile(resolvedPath, "utf-8");
+			}
+			const emptyMsg = checkEmptyContent(content);
+			if (emptyMsg) return {
+				content: emptyMsg,
+				mimeType
+			};
+			const lines = content.split("\n");
+			const startIdx = offset;
+			const endIdx = Math.min(startIdx + limit, lines.length);
+			if (startIdx >= lines.length) return { error: `Line offset ${offset} exceeds file length (${lines.length} lines)` };
+			return {
+				content: lines.slice(startIdx, endIdx).join("\n"),
+				mimeType
+			};
+		} catch (e) {
+			return { error: `Error reading file '${filePath}': ${e.message}` };
+		}
+	}
+	/**
+	* Read file content as raw FileData.
+	*
+	* @param filePath - Absolute file path
+	* @returns ReadRawResult with raw file data on success or error on failure
+	*/
+	async readRaw(filePath) {
+		const resolvedPath = this.resolvePath(filePath);
+		const mimeType = getMimeType(filePath);
+		const isBinary = !isTextMimeType(mimeType);
+		let content;
+		let stat;
+		if (SUPPORTS_NOFOLLOW) {
+			stat = await fs$1.stat(resolvedPath);
+			if (!stat.isFile()) return { error: `File '${filePath}' not found` };
+			const fd = await fs$1.open(resolvedPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+			try {
+				if (isBinary) {
+					const buffer = await fd.readFile();
+					return { data: {
+						content: new Uint8Array(buffer),
+						mimeType,
+						created_at: stat.ctime.toISOString(),
+						modified_at: stat.mtime.toISOString()
+					} };
+				}
+				content = await fd.readFile({ encoding: "utf-8" });
+			} finally {
+				await fd.close();
+			}
+		} else {
+			stat = await fs$1.lstat(resolvedPath);
+			if (stat.isSymbolicLink()) return { error: `Symlinks are not allowed: ${filePath}` };
+			if (!stat.isFile()) return { error: `File '${filePath}' not found` };
+			if (isBinary) {
+				const buffer = await fs$1.readFile(resolvedPath);
+				return { data: {
+					content: new Uint8Array(buffer),
+					mimeType,
+					created_at: stat.ctime.toISOString(),
+					modified_at: stat.mtime.toISOString()
+				} };
+			}
+			content = await fs$1.readFile(resolvedPath, "utf-8");
+		}
+		return { data: {
+			content,
+			mimeType,
+			created_at: stat.ctime.toISOString(),
+			modified_at: stat.mtime.toISOString()
+		} };
+	}
+	/**
+	* Create a new file with content.
+	* Returns WriteResult. External storage sets filesUpdate=null.
+	*/
+	async write(filePath, content) {
+		try {
+			const resolvedPath = this.resolvePath(filePath);
+			const isBinary = !isTextMimeType(getMimeType(filePath));
+			try {
+				if ((await fs$1.lstat(resolvedPath)).isSymbolicLink()) return { error: `Cannot write to ${filePath} because it is a symlink. Symlinks are not allowed.` };
+				return { error: `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.` };
+			} catch {}
+			await fs$1.mkdir(path.dirname(resolvedPath), { recursive: true });
+			if (SUPPORTS_NOFOLLOW) {
+				const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | fs.constants.O_NOFOLLOW;
+				const fd = await fs$1.open(resolvedPath, flags, 420);
+				try {
+					if (isBinary) {
+						const buffer = Buffer.from(content, "base64");
+						await fd.writeFile(buffer);
+					} else await fd.writeFile(content, "utf-8");
+				} finally {
+					await fd.close();
+				}
+			} else if (isBinary) {
+				const buffer = Buffer.from(content, "base64");
+				await fs$1.writeFile(resolvedPath, buffer);
+			} else await fs$1.writeFile(resolvedPath, content, "utf-8");
+			return {
+				path: filePath,
+				filesUpdate: null
+			};
+		} catch (e) {
+			return { error: `Error writing file '${filePath}': ${e.message}` };
+		}
+	}
+	/**
+	* Edit a file by replacing string occurrences.
+	* Returns EditResult. External storage sets filesUpdate=null.
+	*/
+	async edit(filePath, oldString, newString, replaceAll = false) {
+		try {
+			const resolvedPath = this.resolvePath(filePath);
+			let content;
+			if (SUPPORTS_NOFOLLOW) {
+				if (!(await fs$1.stat(resolvedPath)).isFile()) return { error: `Error: File '${filePath}' not found` };
+				const fd = await fs$1.open(resolvedPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+				try {
+					content = await fd.readFile({ encoding: "utf-8" });
+				} finally {
+					await fd.close();
+				}
+			} else {
+				const stat = await fs$1.lstat(resolvedPath);
+				if (stat.isSymbolicLink()) return { error: `Error: Symlinks are not allowed: ${filePath}` };
+				if (!stat.isFile()) return { error: `Error: File '${filePath}' not found` };
+				content = await fs$1.readFile(resolvedPath, "utf-8");
+			}
+			const result = performStringReplacement(content, oldString, newString, replaceAll);
+			if (typeof result === "string") return { error: result };
+			const [newContent, occurrences] = result;
+			if (SUPPORTS_NOFOLLOW) {
+				const flags = fs.constants.O_WRONLY | fs.constants.O_TRUNC | fs.constants.O_NOFOLLOW;
+				const fd = await fs$1.open(resolvedPath, flags);
+				try {
+					await fd.writeFile(newContent, "utf-8");
+				} finally {
+					await fd.close();
+				}
+			} else await fs$1.writeFile(resolvedPath, newContent, "utf-8");
+			return {
+				path: filePath,
+				filesUpdate: null,
+				occurrences
+			};
+		} catch (e) {
+			return { error: `Error editing file '${filePath}': ${e.message}` };
+		}
+	}
+	/**
+	* Search for a literal text pattern in files.
+	*
+	* Uses ripgrep if available, falling back to substring search.
+	*
+	* @param pattern - Literal string to search for (NOT regex).
+	* @param dirPath - Directory or file path to search in. Defaults to current directory.
+	* @param glob - Optional glob pattern to filter which files to search.
+	* @returns List of GrepMatch dicts containing path, line number, and matched text.
+	*/
+	async grep(pattern, dirPath = "/", glob = null) {
+		let baseFull;
+		try {
+			baseFull = this.resolvePath(dirPath || ".");
+		} catch {
+			return { matches: [] };
+		}
+		try {
+			await fs$1.stat(baseFull);
+		} catch {
+			return { matches: [] };
+		}
+		let results = await this.ripgrepSearch(pattern, baseFull, glob);
+		if (results === null) results = await this.literalSearch(pattern, baseFull, glob);
+		const matches = [];
+		for (const [fpath, items] of Object.entries(results)) for (const [lineNum, lineText] of items) matches.push({
+			path: fpath,
+			line: lineNum,
+			text: lineText
+		});
+		return { matches };
+	}
+	/**
+	* Search using ripgrep with fixed-string (literal) mode.
+	*
+	* @param pattern - Literal string to search for (unescaped).
+	* @param baseFull - Resolved base path to search in.
+	* @param includeGlob - Optional glob pattern to filter files.
+	* @returns Dict mapping file paths to list of (line_number, line_text) tuples.
+	*          Returns null if ripgrep is unavailable or times out.
+	*/
+	async ripgrepSearch(pattern, baseFull, includeGlob) {
+		return new Promise((resolve) => {
+			const args = ["--json", "-F"];
+			if (includeGlob) args.push("--glob", includeGlob);
+			args.push("--", pattern, baseFull);
+			const proc = spawn("rg", args, { timeout: 3e4 });
+			const results = {};
+			let output = "";
+			proc.stdout.on("data", (data) => {
+				output += data.toString();
+			});
+			proc.on("close", (code) => {
+				if (code !== 0 && code !== 1) {
+					resolve(null);
+					return;
+				}
+				for (const line of output.split("\n")) {
+					if (!line.trim()) continue;
+					try {
+						const data = JSON.parse(line);
+						if (data.type !== "match") continue;
+						const pdata = data.data || {};
+						const ftext = pdata.path?.text;
+						if (!ftext) continue;
+						let virtPath;
+						if (this.virtualMode) try {
+							const resolved = path.resolve(ftext);
+							const relative = path.relative(this.cwd, resolved);
+							if (relative.startsWith("..")) continue;
+							virtPath = "/" + relative.split(path.sep).join("/");
+						} catch {
+							continue;
+						}
+						else virtPath = ftext;
+						const ln = pdata.line_number;
+						const lt = pdata.lines?.text?.replace(/\n$/, "") || "";
+						if (ln === void 0) continue;
+						if (!results[virtPath]) results[virtPath] = [];
+						results[virtPath].push([ln, lt]);
+					} catch {
+						continue;
+					}
+				}
+				resolve(results);
+			});
+			proc.on("error", () => {
+				resolve(null);
+			});
+		});
+	}
+	/**
+	* Fallback search using literal substring matching when ripgrep is unavailable.
+	*
+	* Recursively searches files, respecting maxFileSizeBytes limit.
+	*
+	* @param pattern - Literal string to search for.
+	* @param baseFull - Resolved base path to search in.
+	* @param includeGlob - Optional glob pattern to filter files by name.
+	* @returns Dict mapping file paths to list of (line_number, line_text) tuples.
+	*/
+	async literalSearch(pattern, baseFull, includeGlob) {
+		const results = {};
+		const files = await fg("**/*", {
+			cwd: (await fs$1.stat(baseFull)).isDirectory() ? baseFull : path.dirname(baseFull),
+			absolute: true,
+			onlyFiles: true,
+			dot: true
+		});
+		for (const fp of files) try {
+			if (!isTextMimeType(getMimeType(fp))) continue;
+			if (includeGlob && !micromatch.isMatch(path.basename(fp), includeGlob)) continue;
+			if ((await fs$1.stat(fp)).size > this.maxFileSizeBytes) continue;
+			const lines = (await fs$1.readFile(fp, "utf-8")).split("\n");
+			for (let i = 0; i < lines.length; i++) {
+				const line = lines[i];
+				if (line.includes(pattern)) {
+					let virtPath;
+					if (this.virtualMode) try {
+						const relative = path.relative(this.cwd, fp);
+						if (relative.startsWith("..")) continue;
+						virtPath = "/" + relative.split(path.sep).join("/");
+					} catch {
+						continue;
+					}
+					else virtPath = fp;
+					if (!results[virtPath]) results[virtPath] = [];
+					results[virtPath].push([i + 1, line]);
+				}
+			}
+		} catch {
+			continue;
+		}
+		return results;
+	}
+	/**
+	* Structured glob matching returning FileInfo objects.
+	*/
+	async glob(pattern, searchPath = "/") {
+		if (pattern.startsWith("/")) pattern = pattern.substring(1);
+		const resolvedSearchPath = searchPath === "/" ? this.cwd : this.resolvePath(searchPath);
+		try {
+			if (!(await fs$1.stat(resolvedSearchPath)).isDirectory()) return { files: [] };
+		} catch {
+			return { files: [] };
+		}
+		const results = [];
+		try {
+			const matches = await fg(pattern, {
+				cwd: resolvedSearchPath,
+				absolute: true,
+				onlyFiles: true,
+				dot: true
+			});
+			for (const matchedPath of matches) try {
+				const stat = await fs$1.stat(matchedPath);
+				if (!stat.isFile()) continue;
+				const normalizedPath = matchedPath.split("/").join(path.sep);
+				if (!this.virtualMode) results.push({
+					path: normalizedPath,
+					is_dir: false,
+					size: stat.size,
+					modified_at: stat.mtime.toISOString()
+				});
+				else {
+					const cwdStr = this.cwd.endsWith(path.sep) ? this.cwd : this.cwd + path.sep;
+					let relativePath;
+					if (normalizedPath.startsWith(cwdStr)) relativePath = normalizedPath.substring(cwdStr.length);
+					else if (normalizedPath.startsWith(this.cwd)) relativePath = normalizedPath.substring(this.cwd.length).replace(/^[/\\]/, "");
+					else relativePath = normalizedPath;
+					relativePath = relativePath.split(path.sep).join("/");
+					const virt = "/" + relativePath;
+					results.push({
+						path: virt,
+						is_dir: false,
+						size: stat.size,
+						modified_at: stat.mtime.toISOString()
+					});
+				}
+			} catch {
+				continue;
+			}
+		} catch {}
+		results.sort((a, b) => a.path.localeCompare(b.path));
+		return { files: results };
+	}
+	/**
+	* Upload multiple files 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$1.mkdir(path.dirname(resolvedPath), { recursive: true });
+			await fs$1.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$1.readFile(resolvedPath);
+			responses.push({
+				path: filePath,
+				content,
+				error: null
+			});
+		} catch (e) {
+			if (e.code === "ENOENT") responses.push({
+				path: filePath,
+				content: null,
+				error: "file_not_found"
+			});
+			else if (e.code === "EACCES") responses.push({
+				path: filePath,
+				content: null,
+				error: "permission_denied"
+			});
+			else if (e.code === "EISDIR") responses.push({
+				path: filePath,
+				content: null,
+				error: "is_directory"
+			});
+			else responses.push({
+				path: filePath,
+				content: null,
+				error: "invalid_path"
+			});
+		}
+		return responses;
+	}
+};
+//#endregion
+//#region src/backends/local-shell.ts
+/**
+* LocalShellBackend: Node.js implementation of the filesystem backend with unrestricted local shell execution.
+*
+* This backend extends FilesystemBackend to add shell command execution on the local
+* host system. It provides NO sandboxing or isolation - all operations run directly
+* on the host machine with full system access.
+*
+* @module
+*/
+/**
+* Filesystem backend with unrestricted local shell command execution.
+*
+* This backend extends FilesystemBackend to add shell command execution
+* capabilities. Commands are executed directly on the host system without any
+* sandboxing, process isolation, or security restrictions.
+*
+* **Security Warning:**
+* This backend grants agents BOTH direct filesystem access AND unrestricted
+* shell execution on your local machine. Use with extreme caution and only in
+* appropriate environments.
+*
+* **Appropriate use cases:**
+* - Local development CLIs (coding assistants, development tools)
+* - Personal development environments where you trust the agent's code
+* - CI/CD pipelines with proper secret management
+*
+* **Inappropriate use cases:**
+* - Production environments (e.g., web servers, APIs, multi-tenant systems)
+* - Processing untrusted user input or executing untrusted code
+*
+* Use StateBackend, StoreBackend, or extend BaseSandbox for production.
+*
+* @example
+* ```typescript
+* import { LocalShellBackend } from "@langchain/deepagents";
+*
+* // Create backend with explicit environment
+* const backend = new LocalShellBackend({
+*   rootDir: "/home/user/project",
+*   virtualMode: true,
+*   env: { PATH: "/usr/bin:/bin" },
+* });
+*
+* // Execute shell commands (runs directly on host)
+* const result = await backend.execute("ls -la");
+* console.log(result.output);
+* console.log(result.exitCode);
+*
+* // Use filesystem operations (inherited from FilesystemBackend)
+* const content = await backend.read("/README.md");
+* await backend.write("/output.txt", "Hello world");
+*
+* // Inherit all environment variables
+* const backend2 = new LocalShellBackend({
+*   rootDir: "/home/user/project",
+*   virtualMode: true,
+*   inheritEnv: true,
+* });
+* ```
+*/
+var LocalShellBackend = class LocalShellBackend extends FilesystemBackend {
+	#timeout;
+	#maxOutputBytes;
+	#env;
+	#sandboxId;
+	#initialized = false;
+	constructor(options = {}) {
+		const { rootDir, virtualMode = false, timeout = 120, maxOutputBytes = 1e5, env, inheritEnv = false } = options;
+		super({
+			rootDir,
+			virtualMode,
+			maxFileSizeMb: 10
+		});
+		this.#timeout = timeout;
+		this.#maxOutputBytes = maxOutputBytes;
+		const bytes = /* @__PURE__ */ new Uint8Array(4);
+		crypto.getRandomValues(bytes);
+		this.#sandboxId = `local-${[...bytes].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+		if (inheritEnv) {
+			this.#env = { ...process.env };
+			if (env) Object.assign(this.#env, env);
+		} else this.#env = env ?? {};
+	}
+	/** Unique identifier for this backend instance (format: "local-{random_hex}"). */
+	get id() {
+		return this.#sandboxId;
+	}
+	/** Whether the backend has been initialized and is ready to use. */
+	get isInitialized() {
+		return this.#initialized;
+	}
+	/** Alias for `isInitialized`, matching the standard sandbox interface. */
+	get isRunning() {
+		return this.#initialized;
+	}
+	/**
+	* Initialize the backend by ensuring the rootDir exists.
+	*
+	* Creates the rootDir (and any parent directories) if it does not already
+	* exist. Safe to call on an existing directory. Must be called before
+	* `execute()`, or use the static `LocalShellBackend.create()` factory.
+	*
+	* @throws {SandboxError} If already initialized (`ALREADY_INITIALIZED`)
+	*/
+	async initialize() {
+		if (this.#initialized) throw new SandboxError("Backend is already initialized. Each LocalShellBackend instance can only be initialized once.", "ALREADY_INITIALIZED");
+		await fs$1.mkdir(this.cwd, { recursive: true });
+		this.#initialized = true;
+	}
+	/**
+	* Mark the backend as no longer running.
+	*
+	* For local shell backends there is no remote resource to tear down,
+	* so this simply flips the `isRunning` / `isInitialized` flag.
+	*/
+	async close() {
+		this.#initialized = false;
+	}
+	/**
+	* Read a file, adapting error messages to the standard sandbox format.
+	*/
+	async read(filePath, offset = 0, limit = 500) {
+		const result = await super.read(filePath, offset, limit);
+		if (result.error?.includes("ENOENT")) return { error: `File '${filePath}' not found` };
+		return result;
+	}
+	/**
+	* Edit a file, adapting error messages to the standard sandbox format.
+	*/
+	async edit(filePath, oldString, newString, replaceAll = false) {
+		const result = await super.edit(filePath, oldString, newString, replaceAll);
+		if (result.error?.includes("ENOENT")) return {
+			...result,
+			error: `Error: File '${filePath}' not found`
+		};
+		return result;
+	}
+	/**
+	* List directory contents, returning paths relative to rootDir.
+	*/
+	async ls(dirPath) {
+		const result = await super.ls(dirPath);
+		if (result.error) return result;
+		if (this.virtualMode) return result;
+		const cwdPrefix = this.cwd.endsWith(path.sep) ? this.cwd : this.cwd + path.sep;
+		return { files: (result.files || []).map((info) => ({
+			...info,
+			path: info.path.startsWith(cwdPrefix) ? info.path.slice(cwdPrefix.length) : info.path
+		})) };
+	}
+	/**
+	* Glob matching that returns relative paths and includes directories.
+	*/
+	async glob(pattern, searchPath = "/") {
+		if (pattern.startsWith("/")) pattern = pattern.substring(1);
+		const resolvedSearchPath = searchPath === "/" || searchPath === "" ? this.cwd : this.virtualMode ? path.resolve(this.cwd, searchPath.replace(/^\//, "")) : path.resolve(this.cwd, searchPath);
+		try {
+			if (!(await fs$1.stat(resolvedSearchPath)).isDirectory()) return { files: [] };
+		} catch {
+			return { files: [] };
+		}
+		const formatPath = (rel) => this.virtualMode ? `/${rel}` : rel;
+		const globOpts = {
+			cwd: resolvedSearchPath,
+			absolute: false,
+			dot: true
+		};
+		const [fileMatches, dirMatches] = await Promise.all([fg(pattern, {
+			...globOpts,
+			onlyFiles: true
+		}), fg(pattern, {
+			...globOpts,
+			onlyDirectories: true
+		})]);
+		const statFile = async (match) => {
+			try {
+				const entryStat = await fs$1.stat(path.join(resolvedSearchPath, match));
+				if (entryStat.isFile()) return {
+					path: formatPath(match),
+					is_dir: false,
+					size: entryStat.size,
+					modified_at: entryStat.mtime.toISOString()
+				};
+			} catch {}
+			return null;
+		};
+		const statDir = async (match) => {
+			try {
+				const entryStat = await fs$1.stat(path.join(resolvedSearchPath, match));
+				if (entryStat.isDirectory()) return {
+					path: formatPath(match),
+					is_dir: true,
+					size: 0,
+					modified_at: entryStat.mtime.toISOString()
+				};
+			} catch {}
+			return null;
+		};
+		const [fileInfos, dirInfos] = await Promise.all([Promise.all(fileMatches.map(statFile)), Promise.all(dirMatches.map(statDir))]);
+		const results = [...fileInfos, ...dirInfos].filter((info) => info !== null);
+		results.sort((a, b) => a.path.localeCompare(b.path));
+		return { files: results };
+	}
+	/**
+	* Execute a shell command directly on the host system.
+	*
+	* Commands are executed directly on your host system using `spawn()`
+	* with `shell: true`. There is NO sandboxing, isolation, or security
+	* restrictions. The command runs with your user's full permissions.
+	*
+	* The command is executed using the system shell with the working directory
+	* set to the backend's rootDir. Stdout and stderr are combined into a single
+	* output stream, with stderr lines prefixed with `[stderr]`.
+	*
+	* @param command - Shell command string to execute
+	* @returns ExecuteResponse containing output, exit code, and truncation flag
+	*/
+	async execute(command) {
+		if (!command || typeof command !== "string") return {
+			output: "Error: Command must be a non-empty string.",
+			exitCode: 1,
+			truncated: false
+		};
+		return new Promise((resolve) => {
+			let stdout = "";
+			let stderr = "";
+			let timedOut = false;
+			const child = cp.spawn(command, {
+				shell: true,
+				env: this.#env,
+				cwd: this.cwd
+			});
+			const timer = setTimeout(() => {
+				timedOut = true;
+				child.kill("SIGTERM");
+			}, this.#timeout * 1e3);
+			child.stdout.on("data", (data) => {
+				stdout += data.toString();
+			});
+			child.stderr.on("data", (data) => {
+				stderr += data.toString();
+			});
+			child.on("error", (err) => {
+				clearTimeout(timer);
+				resolve({
+					output: `Error executing command: ${err.message}`,
+					exitCode: 1,
+					truncated: false
+				});
+			});
+			child.on("close", (code, signal) => {
+				clearTimeout(timer);
+				if (timedOut || signal === "SIGTERM") {
+					resolve({
+						output: `Error: Command timed out after ${this.#timeout.toFixed(1)} seconds.`,
+						exitCode: 124,
+						truncated: false
+					});
+					return;
+				}
+				const outputParts = [];
+				if (stdout) outputParts.push(stdout);
+				if (stderr) {
+					const stderrLines = stderr.trim().split("\n");
+					outputParts.push(...stderrLines.map((line) => `[stderr] ${line}`));
+				}
+				let output = outputParts.length > 0 ? outputParts.join("\n") : "<no output>";
+				let truncated = false;
+				if (output.length > this.#maxOutputBytes) {
+					output = output.slice(0, this.#maxOutputBytes);
+					output += `\n\n... Output truncated at ${this.#maxOutputBytes} bytes.`;
+					truncated = true;
+				}
+				const exitCode = code ?? 1;
+				if (exitCode !== 0) output = `${output.trimEnd()}\n\nExit code: ${exitCode}`;
+				resolve({
+					output,
+					exitCode,
+					truncated
+				});
+			});
+		});
+	}
+	/**
+	* Create and initialize a new LocalShellBackend in one step.
+	*
+	* This is the recommended way to create a backend when the rootDir may
+	* not exist yet. It combines construction and initialization (ensuring
+	* rootDir exists) into a single async operation.
+	*
+	* @param options - Configuration options for the backend
+	* @returns An initialized and ready-to-use backend
+	*/
+	static async create(options = {}) {
+		const { initialFiles, ...backendOptions } = options;
+		const backend = new LocalShellBackend(backendOptions);
+		await backend.initialize();
+		if (initialFiles) {
+			const encoder = new TextEncoder();
+			const files = Object.entries(initialFiles).map(([filePath, content]) => [filePath, encoder.encode(content)]);
+			await backend.uploadFiles(files);
+		}
+		return backend;
+	}
+};
+//#endregion
+export { createAgentMemoryMiddleware as a, parseSkillMetadata as i, FilesystemBackend as n, createSettings as o, listSkills as r, findProjectRoot as s, LocalShellBackend as t };
+
+//# sourceMappingURL=src-DybKvM4T.js.map