deepagents 0.0.2 → 1.0.0-beta.2

package/dist/index.js

@@ -1,12 +1,899 @@
+import { AIMessage, ToolMessage, anthropicPromptCachingMiddleware, createAgent, createMiddleware, humanInTheLoopMiddleware, summarizationMiddleware, todoListMiddleware, tool } from "langchain";
+import { Command, REMOVE_ALL_MESSAGES, getConfig, getCurrentTaskInput, isCommand } from "@langchain/langgraph";
+import { z } from "zod/v3";
+import { withLangGraph } from "@langchain/langgraph/zod";
+import { HumanMessage, RemoveMessage } from "@langchain/core/messages";
+
+//#region src/middleware/fs.ts
+const MEMORIES_PREFIX = "/memories/";
+const EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents";
+const MAX_LINE_LENGTH = 2e3;
+const LINE_NUMBER_WIDTH = 6;
+const DEFAULT_READ_OFFSET = 0;
+const DEFAULT_READ_LIMIT = 2e3;
 /**
- * Deep Agents TypeScript Implementation
- *
- * A TypeScript port of the Python Deep Agents library for building controllable AI agents with LangGraph.
- * This implementation maintains 1:1 compatibility with the Python version.
- */
-export { createDeepAgent } from "./graph.js";
-export { getDefaultModel } from "./model.js";
-export { createTaskTool } from "./subAgent.js";
-export { writeTodos, readFile, writeFile, editFile, ls } from "./tools.js";
-export { DeepAgentState, fileReducer } from "./state.js";
-export { WRITE_TODOS_DESCRIPTION, TASK_DESCRIPTION_PREFIX, TASK_DESCRIPTION_SUFFIX, EDIT_DESCRIPTION, TOOL_DESCRIPTION, } from "./prompts.js";
+* Zod v3 schema for FileData
+*/
+const FileDataSchema = z.object({
+	content: z.array(z.string()),
+	created_at: z.string(),
+	modified_at: z.string()
+});
+/**
+* Merge file updates with support for deletions.
+*
+* This reducer enables file deletion by treating `null` values in the right
+* dictionary as deletion markers. It's designed to work with LangGraph's
+* state management where annotated reducers control how state updates merge.
+*/
+function fileDataReducer(left, right) {
+	if (left === void 0) {
+		const result$1 = {};
+		for (const [key, value] of Object.entries(right)) if (value !== null) result$1[key] = value;
+		return result$1;
+	}
+	const result = { ...left };
+	for (const [key, value] of Object.entries(right)) if (value === null) delete result[key];
+	else result[key] = value;
+	return result;
+}
+/**
+* Validate and normalize file path for security.
+*
+* Ensures paths are safe to use by preventing directory traversal attacks
+* and enforcing consistent formatting. All paths are normalized to use
+* forward slashes and start with a leading slash.
+*/
+function validatePath(path, options) {
+	if (path.includes("..") || path.startsWith("~")) throw new Error(`Path traversal not allowed: ${path}`);
+	let normalized = path.replace(/\/+/g, "/").replace(/\/\./g, "/").replace(/\\/g, "/");
+	if (!normalized.startsWith("/")) normalized = `/${normalized}`;
+	if (options?.allowedPrefixes) {
+		if (!options.allowedPrefixes.some((prefix) => normalized.startsWith(prefix))) throw new Error(`Path must start with one of ${options.allowedPrefixes.join(", ")}: ${path}`);
+	}
+	return normalized;
+}
+/**
+* Format file content with line numbers for display.
+*
+* Converts file content to a numbered format similar to `cat -n` output,
+* with support for two different formatting styles.
+*/
+function formatContentWithLineNumbers(content, options = {}) {
+	const { formatStyle = "pipe", startLine = 1 } = options;
+	let lines;
+	if (typeof content === "string") {
+		lines = content.split("\n");
+		if (lines.length > 0 && lines[lines.length - 1] === "") lines = lines.slice(0, -1);
+	} else lines = content;
+	if (formatStyle === "pipe") return lines.map((line, i) => `${i + startLine}|${line}`).join("\n");
+	return lines.map((line, i) => `${(i + startLine).toString().padStart(LINE_NUMBER_WIDTH)}\t${line.slice(0, MAX_LINE_LENGTH)}`).join("\n");
+}
+/**
+* Create a FileData object with automatic timestamp generation.
+*/
+function createFileData(content, options) {
+	const lines = typeof content === "string" ? content.split("\n") : content;
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		content: lines,
+		created_at: options?.createdAt || now,
+		modified_at: now
+	};
+}
+/**
+* Update FileData with new content while preserving creation timestamp.
+*/
+function updateFileData(fileData, content) {
+	const lines = typeof content === "string" ? content.split("\n") : content;
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		content: lines,
+		created_at: fileData.created_at,
+		modified_at: now
+	};
+}
+/**
+* Convert FileData to plain string content.
+*/
+function fileDataToString(fileData) {
+	return fileData.content.join("\n");
+}
+/**
+* Check if file content is empty and return a warning message.
+*/
+function checkEmptyContent(content) {
+	if (!content || content.trim() === "") return EMPTY_CONTENT_WARNING;
+	return null;
+}
+/**
+* Check if a file path is in the longterm memory filesystem.
+*/
+function hasMemoriesPrefix(filePath) {
+	return filePath.startsWith(MEMORIES_PREFIX);
+}
+/**
+* Add the longterm memory prefix to a file path.
+*/
+function appendMemoriesPrefix(filePath) {
+	return `/memories${filePath}`;
+}
+/**
+* Remove the longterm memory prefix from a file path.
+*/
+function stripMemoriesPrefix(filePath) {
+	if (filePath.startsWith(MEMORIES_PREFIX)) return filePath.slice(9);
+	return filePath;
+}
+/**
+* Get the namespace for longterm filesystem storage.
+*
+* Returns a tuple for organizing files in the store. If an assistant_id is available
+* in the config metadata, returns a 2-tuple of (assistant_id, "filesystem") to provide
+* per-assistant isolation. Otherwise, returns a 1-tuple of ("filesystem",) for shared storage.
+*
+* @returns Namespace tuple for store operations, either [assistant_id, "filesystem"] or ["filesystem"]
+*/
+function getNamespace() {
+	const namespace = "filesystem";
+	try {
+		const config = getConfig();
+		if (!config) return [namespace];
+		const assistantId = config.metadata?.assistant_id;
+		if (!assistantId) return [namespace];
+		return [assistantId, namespace];
+	} catch {
+		return [namespace];
+	}
+}
+/**
+* Convert a store Item to FileData format.
+*/
+function convertStoreItemToFileData(storeItem) {
+	const value = storeItem.value;
+	if (!Array.isArray(value.content)) throw new Error(`Store item does not contain valid content field. Got: ${Object.keys(value).join(", ")}`);
+	if (typeof value.created_at !== "string") throw new Error(`Store item does not contain valid created_at field. Got: ${Object.keys(value).join(", ")}`);
+	if (typeof value.modified_at !== "string") throw new Error(`Store item does not contain valid modified_at field. Got: ${Object.keys(value).join(", ")}`);
+	return {
+		content: value.content,
+		created_at: value.created_at,
+		modified_at: value.modified_at
+	};
+}
+/**
+* Convert FileData to a dict suitable for store.put().
+*/
+function convertFileDataToStoreItem(fileData) {
+	return {
+		content: fileData.content,
+		created_at: fileData.created_at,
+		modified_at: fileData.modified_at
+	};
+}
+const stateSchema = z.object({ files: withLangGraph(z.record(z.string(), FileDataSchema).default(() => ({})), { reducer: {
+	fn: fileDataReducer,
+	schema: z.record(z.string(), FileDataSchema.nullable())
+} }) });
+const LIST_FILES_TOOL_DESCRIPTION = `Lists all files in the filesystem, optionally filtering by directory.
+
+Usage:
+- The ls tool will return a list of all files in the filesystem.
+- You can optionally provide a path parameter to list files in a specific directory.
+- This is very useful for exploring the file system and finding the right file to read or edit.
+- You should almost ALWAYS use this tool before using the read_file or edit_file tools.`;
+const LIST_FILES_TOOL_DESCRIPTION_LONGTERM_SUPPLEMENT = `\n- Files from the longterm filesystem will be prefixed with the ${MEMORIES_PREFIX} path.`;
+const READ_FILE_TOOL_DESCRIPTION = `Reads a file from the filesystem. You can access any file directly by using this tool.
+Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- The file_path parameter must be an absolute path, not a relative path
+- By default, it reads up to 2000 lines starting from the beginning of the file
+- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
+- Any lines longer than 2000 characters will be truncated
+- Results are returned using cat -n format, with line numbers starting at 1
+- You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.
+- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
+- You should ALWAYS make sure a file has been read before editing it.`;
+const READ_FILE_TOOL_DESCRIPTION_LONGTERM_SUPPLEMENT = `\n- file_paths prefixed with the ${MEMORIES_PREFIX} path will be read from the longterm filesystem.`;
+const EDIT_FILE_TOOL_DESCRIPTION = `Performs exact string replacements in files.
+
+Usage:
+- You must use your read_file tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
+- When editing text from read_file tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
+- ALWAYS prefer editing existing files. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- The edit will FAIL if \`old_string\` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use \`replace_all\` to change every instance of \`old_string\`.
+- Use \`replace_all\` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.`;
+const EDIT_FILE_TOOL_DESCRIPTION_LONGTERM_SUPPLEMENT = `\n- You can edit files in the longterm filesystem by prefixing the filename with the ${MEMORIES_PREFIX} path.`;
+const WRITE_FILE_TOOL_DESCRIPTION = `Writes to a new file in the filesystem.
+
+Usage:
+- The file_path parameter must be an absolute path, not a relative path
+- The content parameter must be a string
+- The write_file tool will create a new file.
+- Prefer to edit existing files over creating new ones when possible.`;
+const WRITE_FILE_TOOL_DESCRIPTION_LONGTERM_SUPPLEMENT = `\n- file_paths prefixed with the ${MEMORIES_PREFIX} path will be written to the longterm filesystem.`;
+const FILESYSTEM_SYSTEM_PROMPT = `## Filesystem Tools \`ls\`, \`read_file\`, \`write_file\`, \`edit_file\`
+
+You have access to a filesystem which you can interact with using these tools.
+All file paths must start with a /.
+
+- ls: list all files in the filesystem
+- read_file: read a file from the filesystem
+- write_file: write to a file in the filesystem
+- edit_file: edit a file in the filesystem`;
+const FILESYSTEM_SYSTEM_PROMPT_LONGTERM_SUPPLEMENT = `
+
+You also have access to a longterm filesystem in which you can store files that you want to keep around for longer than the current conversation.
+In order to interact with the longterm filesystem, you can use those same tools, but filenames must be prefixed with the ${MEMORIES_PREFIX} path.
+Remember, to interact with the longterm filesystem, you must prefix the filename with the ${MEMORIES_PREFIX} path.`;
+const TOO_LARGE_TOOL_MSG = `Tool result too large, the result of this tool call {tool_call_id} was saved in the filesystem at this path: {file_path}
+You can read the result from the filesystem by using the read_file tool, but make sure to only read part of the result at a time.
+You can do this by specifying an offset and limit in the read_file tool call.
+For example, to read the first 100 lines, you can use the read_file tool with offset=0 and limit=100.
+
+Here are the first 10 lines of the result:
+{content_sample}
+`;
+function assertStore(config) {
+	if (!("store" in config) || config.store == null) throw new Error("Missing store when long term memory is enabled");
+}
+/**
+* Generate the ls (list files) tool.
+*/
+function createLsTool(customDescription, longTermMemory) {
+	let toolDescription = LIST_FILES_TOOL_DESCRIPTION;
+	if (customDescription) toolDescription = customDescription;
+	else if (longTermMemory) toolDescription += LIST_FILES_TOOL_DESCRIPTION_LONGTERM_SUPPLEMENT;
+	return tool(async (input, config) => {
+		const filesDict = getCurrentTaskInput(config).files || {};
+		let files = Object.keys(filesDict);
+		if (longTermMemory) {
+			assertStore(config);
+			const namespace = getNamespace();
+			const longtermFilesPrefixed = (await config.store.search(namespace)).map((f) => appendMemoriesPrefix(f.key));
+			files = files.concat(longtermFilesPrefixed);
+		}
+		if (input.path) {
+			const normalizedPath = validatePath(input.path);
+			files = files.filter((f) => f.startsWith(normalizedPath));
+		}
+		return files;
+	}, {
+		name: "ls",
+		description: toolDescription,
+		schema: z.object({ path: z.string().optional().describe("Optional path to filter by") })
+	});
+}
+/**
+* Generate the read_file tool.
+*/
+function createReadFileTool(customDescription, longTermMemory) {
+	let toolDescription = READ_FILE_TOOL_DESCRIPTION;
+	if (customDescription) toolDescription = customDescription;
+	else if (longTermMemory) toolDescription += READ_FILE_TOOL_DESCRIPTION_LONGTERM_SUPPLEMENT;
+	function readFileDataContent(fileData, offset, limit) {
+		const content = fileDataToString(fileData);
+		const emptyMsg = checkEmptyContent(content);
+		if (emptyMsg) return emptyMsg;
+		const lines = content.split("\n");
+		const startIdx = offset;
+		const endIdx = Math.min(startIdx + limit, lines.length);
+		if (startIdx >= lines.length) return `Error: Line offset ${offset} exceeds file length (${lines.length} lines)`;
+		return formatContentWithLineNumbers(lines.slice(startIdx, endIdx), {
+			formatStyle: "tab",
+			startLine: startIdx + 1
+		});
+	}
+	return tool(async (input, config) => {
+		const filePath = validatePath(input.file_path);
+		const offset = input.offset ?? DEFAULT_READ_OFFSET;
+		const limit = input.limit ?? DEFAULT_READ_LIMIT;
+		if (longTermMemory) {
+			assertStore(config);
+			if (hasMemoriesPrefix(filePath)) {
+				const strippedFilePath = stripMemoriesPrefix(filePath);
+				const namespace = getNamespace();
+				const item = await config.store?.get(namespace, strippedFilePath);
+				if (!item) return `Error: File '${filePath}' not found`;
+				return readFileDataContent(convertStoreItemToFileData(item), offset, limit);
+			}
+		}
+		const mockFilesystem = getCurrentTaskInput(config).files || {};
+		if (!(filePath in mockFilesystem)) return `Error: File '${filePath}' not found`;
+		const fileData = mockFilesystem[filePath];
+		return readFileDataContent(fileData, offset, limit);
+	}, {
+		name: "read_file",
+		description: toolDescription,
+		schema: z.object({
+			file_path: z.string().describe("Absolute path to the file to read"),
+			offset: z.number({ coerce: true }).optional().default(DEFAULT_READ_OFFSET).describe("Line offset to start reading from"),
+			limit: z.number({ coerce: true }).optional().default(DEFAULT_READ_LIMIT).describe("Maximum number of lines to read")
+		})
+	});
+}
+/**
+* Generate the write_file tool.
+*/
+function createWriteFileTool(customDescription, longTermMemory) {
+	let toolDescription = WRITE_FILE_TOOL_DESCRIPTION;
+	if (customDescription) toolDescription = customDescription;
+	else if (longTermMemory) toolDescription += WRITE_FILE_TOOL_DESCRIPTION_LONGTERM_SUPPLEMENT;
+	return tool(async (input, config) => {
+		const filePath = validatePath(input.file_path);
+		if (longTermMemory) {
+			assertStore(config);
+			if (hasMemoriesPrefix(filePath)) {
+				const strippedFilePath = stripMemoriesPrefix(filePath);
+				const namespace = getNamespace();
+				if (await config.store.get(namespace, strippedFilePath)) return `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.`;
+				const newFileData$1 = createFileData(input.content);
+				await config.store.put(namespace, strippedFilePath, convertFileDataToStoreItem(newFileData$1));
+				return `Updated longterm memories file ${filePath}`;
+			}
+		}
+		if (filePath in (getCurrentTaskInput(config).files || {})) return `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.`;
+		const newFileData = createFileData(input.content);
+		return new Command({ update: {
+			files: { [filePath]: newFileData },
+			messages: [new ToolMessage({
+				content: `Updated file ${filePath}`,
+				tool_call_id: config.toolCall?.id,
+				name: "write_file"
+			})]
+		} });
+	}, {
+		name: "write_file",
+		description: toolDescription,
+		schema: z.object({
+			file_path: z.string().describe("Absolute path to the file to write"),
+			content: z.string().describe("Content to write to the file")
+		})
+	});
+}
+/**
+* Generate the edit_file tool.
+*/
+function createEditFileTool(customDescription, longTermMemory) {
+	let toolDescription = EDIT_FILE_TOOL_DESCRIPTION;
+	if (customDescription) toolDescription = customDescription;
+	else if (longTermMemory) toolDescription += EDIT_FILE_TOOL_DESCRIPTION_LONGTERM_SUPPLEMENT;
+	function performFileEdit(fileData, oldString, newString, replaceAll) {
+		const content = fileDataToString(fileData);
+		const occurrences = (content.match(new RegExp(oldString.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g")) || []).length;
+		if (occurrences === 0) return `Error: String not found in file: '${oldString}'`;
+		if (occurrences > 1 && !replaceAll) return `Error: String '${oldString}' appears ${occurrences} times in file. Use replace_all=True to replace all instances, or provide a more specific string with surrounding context.`;
+		return {
+			fileData: updateFileData(fileData, content.replace(new RegExp(oldString.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), replaceAll ? "g" : ""), newString)),
+			message: `Successfully replaced ${occurrences} instance(s) of the string`
+		};
+	}
+	return tool(async (input, config) => {
+		const filePath = validatePath(input.file_path);
+		const replaceAll = input.replace_all ?? false;
+		const fileData = await (async () => {
+			if (longTermMemory) {
+				assertStore(config);
+				if (hasMemoriesPrefix(filePath)) {
+					const strippedFilePath = stripMemoriesPrefix(filePath);
+					const namespace = getNamespace();
+					const item = await config.store.get(namespace, strippedFilePath);
+					if (!item) return `Error: File '${filePath}' not found`;
+					return convertStoreItemToFileData(item);
+				}
+			}
+			const mockFilesystem = getCurrentTaskInput(config).files || {};
+			if (!(filePath in mockFilesystem)) return `Error: File '${filePath}' not found`;
+			return mockFilesystem[filePath];
+		})();
+		if (typeof fileData === "string") return fileData;
+		const result = performFileEdit(fileData, input.old_string, input.new_string, replaceAll);
+		if (typeof result === "string") return result;
+		const { fileData: newFileData, message: resultMsg } = result;
+		const fullMsg = `${resultMsg} in '${filePath}'`;
+		if (longTermMemory) {
+			assertStore(config);
+			if (hasMemoriesPrefix(filePath)) {
+				const strippedFilePath = stripMemoriesPrefix(filePath);
+				const namespace = getNamespace();
+				await config.store.put(namespace, strippedFilePath, convertFileDataToStoreItem(newFileData));
+				return fullMsg;
+			}
+		}
+		return new Command({ update: {
+			files: { [filePath]: newFileData },
+			messages: [new ToolMessage({
+				content: fullMsg,
+				tool_call_id: config.toolCall?.id,
+				name: "edit_file"
+			})]
+		} });
+	}, {
+		name: "edit_file",
+		description: toolDescription,
+		schema: z.object({
+			file_path: z.string().describe("Absolute path to the file to edit"),
+			old_string: z.string().describe("String to be replaced (must match exactly)"),
+			new_string: z.string().describe("String to replace with"),
+			replace_all: z.boolean().optional().default(false).describe("Whether to replace all occurrences")
+		})
+	});
+}
+/**
+* Create filesystem middleware with all tools and features.
+*/
+function createFilesystemMiddleware(options = {}) {
+	const { longTermMemory = false, systemPrompt: customSystemPrompt = null, customToolDescriptions = null, toolTokenLimitBeforeEvict = 2e4 } = options;
+	let systemPrompt = FILESYSTEM_SYSTEM_PROMPT;
+	if (customSystemPrompt !== null) systemPrompt = customSystemPrompt;
+	else if (longTermMemory) systemPrompt += FILESYSTEM_SYSTEM_PROMPT_LONGTERM_SUPPLEMENT;
+	return createMiddleware({
+		name: "fsMiddleware",
+		stateSchema,
+		tools: [
+			createLsTool(customToolDescriptions?.ls ?? null, longTermMemory),
+			createReadFileTool(customToolDescriptions?.read_file ?? null, longTermMemory),
+			createWriteFileTool(customToolDescriptions?.write_file ?? null, longTermMemory),
+			createEditFileTool(customToolDescriptions?.edit_file ?? null, longTermMemory)
+		],
+		wrapModelCall: async (request, handler) => {
+			const currentSystemPrompt = request.systemPrompt || "";
+			const newSystemPrompt = currentSystemPrompt ? `${currentSystemPrompt}\n\n${systemPrompt}` : systemPrompt;
+			return handler({
+				...request,
+				systemPrompt: newSystemPrompt
+			});
+		},
+		wrapToolCall: async (request, handler) => {
+			if (!toolTokenLimitBeforeEvict || [
+				"ls",
+				"read_file",
+				"write_file",
+				"edit_file"
+			].includes(request.tool.name)) return handler(request);
+			const result = await handler(request);
+			if (ToolMessage.isInstance(result) && typeof result.content === "string") {
+				if (result.content.length > 4 * toolTokenLimitBeforeEvict) {
+					const filePath = `/large_tool_results/${request.toolCall.id}`;
+					const fileData = createFileData(result.content);
+					const contentSample = formatContentWithLineNumbers(fileData.content.slice(0, 10), {
+						formatStyle: "tab",
+						startLine: 1
+					});
+					return new Command({ update: {
+						messages: [new ToolMessage({
+							content: TOO_LARGE_TOOL_MSG.replace("{tool_call_id}", request.toolCall.id || "").replace("{file_path}", filePath).replace("{content_sample}", contentSample),
+							tool_call_id: request.toolCall.id || "",
+							name: request.tool.name
+						})],
+						files: { [filePath]: fileData }
+					} });
+				}
+			} else if (isCommand(result) && result.update) {
+				const update = result.update;
+				const messageUpdates = update.messages || [];
+				const fileUpdates = update.files || {};
+				const editedMessageUpdates = [];
+				for (const message of messageUpdates) {
+					if (toolTokenLimitBeforeEvict && message instanceof ToolMessage && typeof message.content === "string") {
+						if (message.content.length > 4 * toolTokenLimitBeforeEvict) {
+							const filePath = `/large_tool_results/${message.tool_call_id}`;
+							const fileData = createFileData(message.content);
+							const contentSample = formatContentWithLineNumbers(fileData.content.slice(0, 10), {
+								formatStyle: "tab",
+								startLine: 1
+							});
+							const evictedMessage = TOO_LARGE_TOOL_MSG.replace("{tool_call_id}", message.tool_call_id || "").replace("{file_path}", filePath).replace("{content_sample}", contentSample);
+							editedMessageUpdates.push(new ToolMessage({
+								content: evictedMessage,
+								tool_call_id: message.tool_call_id || "",
+								name: message.name || ""
+							}));
+							fileUpdates[filePath] = fileData;
+							continue;
+						}
+					}
+					editedMessageUpdates.push(message);
+				}
+				return new Command({ update: {
+					...update,
+					messages: editedMessageUpdates,
+					files: fileUpdates
+				} });
+			}
+			return result;
+		}
+	});
+}
+const fsMiddleware = createFilesystemMiddleware();
+
+//#endregion
+//#region src/middleware/subagents.ts
+const DEFAULT_SUBAGENT_PROMPT = "In order to complete the objective that the user asks of you, you have access to a number of standard tools.";
+const EXCLUDED_STATE_KEYS = [
+	"messages",
+	"todos",
+	"jumpTo"
+];
+const DEFAULT_GENERAL_PURPOSE_DESCRIPTION = "General-purpose agent for researching complex questions, searching for files and content, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. This agent has access to all tools as the main agent.";
+function getTaskToolDescription(subagentDescriptions) {
+	return `
+Launch an ephemeral subagent to handle complex, multi-step independent tasks with isolated context windows.
+
+Available agent types and the tools they have access to:
+${subagentDescriptions.join("\n")}
+
+When using the Task tool, you must specify a subagent_type parameter to select which agent type to use.
+
+## Usage notes:
+1. Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+2. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
+3. Each agent invocation is stateless. You will not be able to send additional messages to the agent, nor will the agent be able to communicate with you outside of its final report. Therefore, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
+4. The agent's outputs should generally be trusted
+5. Clearly tell the agent whether you expect it to create content, perform analysis, or just do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
+6. If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
+7. When only the general-purpose agent is provided, you should use it for all tasks. It is great for isolating context and token usage, and completing specific, complex tasks, as it has all the same capabilities as the main agent.
+
+### Example usage of the general-purpose agent:
+
+<example_agent_descriptions>
+"general-purpose": use this agent for general purpose tasks, it has access to all tools as the main agent.
+</example_agent_descriptions>
+
+<example>
+User: "I want to conduct research on the accomplishments of Lebron James, Michael Jordan, and Kobe Bryant, and then compare them."
+Assistant: *Uses the task tool in parallel to conduct isolated research on each of the three players*
+Assistant: *Synthesizes the results of the three isolated research tasks and responds to the User*
+<commentary>
+Research is a complex, multi-step task in it of itself.
+The research of each individual player is not dependent on the research of the other players.
+The assistant uses the task tool to break down the complex objective into three isolated tasks.
+Each research task only needs to worry about context and tokens about one player, then returns synthesized information about each player as the Tool Result.
+This means each research task can dive deep and spend tokens and context deeply researching each player, but the final result is synthesized information, and saves us tokens in the long run when comparing the players to each other.
+</commentary>
+</example>
+
+<example>
+User: "Analyze a single large code repository for security vulnerabilities and generate a report."
+Assistant: *Launches a single \`task\` subagent for the repository analysis*
+Assistant: *Receives report and integrates results into final summary*
+<commentary>
+Subagent is used to isolate a large, context-heavy task, even though there is only one. This prevents the main thread from being overloaded with details.
+If the user then asks followup questions, we have a concise report to reference instead of the entire history of analysis and tool calls, which is good and saves us time and money.
+</commentary>
+</example>
+
+<example>
+User: "Schedule two meetings for me and prepare agendas for each."
+Assistant: *Calls the task tool in parallel to launch two \`task\` subagents (one per meeting) to prepare agendas*
+Assistant: *Returns final schedules and agendas*
+<commentary>
+Tasks are simple individually, but subagents help silo agenda preparation.
+Each subagent only needs to worry about the agenda for one meeting.
+</commentary>
+</example>
+
+<example>
+User: "I want to order a pizza from Dominos, order a burger from McDonald's, and order a salad from Subway."
+Assistant: *Calls tools directly in parallel to order a pizza from Dominos, a burger from McDonald's, and a salad from Subway*
+<commentary>
+The assistant did not use the task tool because the objective is super simple and clear and only requires a few trivial tool calls.
+It is better to just complete the task directly and NOT use the \`task\`tool.
+</commentary>
+</example>
+
+### Example usage with custom agents:
+
+<example_agent_descriptions>
+"content-reviewer": use this agent after you are done creating significant content or documents
+"greeting-responder": use this agent when to respond to user greetings with a friendly joke
+"research-analyst": use this agent to conduct thorough research on complex topics
+</example_agent_description>
+
+<example>
+user: "Please write a function that checks if a number is prime"
+assistant: Sure let me write a function that checks if a number is prime
+assistant: First let me use the Write tool to write a function that checks if a number is prime
+assistant: I'm going to use the Write tool to write the following code:
+<code>
+function isPrime(n) {
+  if (n <= 1) return false
+  for (let i = 2; i * i <= n; i++) {
+    if (n % i === 0) return false
+  }
+  return true
+}
+</code>
+<commentary>
+Since significant content was created and the task was completed, now use the content-reviewer agent to review the work
+</commentary>
+assistant: Now let me use the content-reviewer agent to review the code
+assistant: Uses the Task tool to launch with the content-reviewer agent
+</example>
+
+<example>
+user: "Can you help me research the environmental impact of different renewable energy sources and create a comprehensive report?"
+<commentary>
+This is a complex research task that would benefit from using the research-analyst agent to conduct thorough analysis
+</commentary>
+assistant: I'll help you research the environmental impact of renewable energy sources. Let me use the research-analyst agent to conduct comprehensive research on this topic.
+assistant: Uses the Task tool to launch with the research-analyst agent, providing detailed instructions about what research to conduct and what format the report should take
+</example>
+
+<example>
+user: "Hello"
+<commentary>
+Since the user is greeting, use the greeting-responder agent to respond with a friendly joke
+</commentary>
+assistant: "I'm going to use the Task tool to launch with the greeting-responder agent"
+</example>
+  `.trim();
+}
+const TASK_SYSTEM_PROMPT = `## \`task\` (subagent spawner)
+
+You have access to a \`task\` tool to launch short-lived subagents that handle isolated tasks. These agents are ephemeral — they live only for the duration of the task and return a single result.
+
+When to use the task tool:
+- When a task is complex and multi-step, and can be fully delegated in isolation
+- When a task is independent of other tasks and can run in parallel
+- When a task requires focused reasoning or heavy token/context usage that would bloat the orchestrator thread
+- When sandboxing improves reliability (e.g. code execution, structured searches, data formatting)
+- When you only care about the output of the subagent, and not the intermediate steps (ex. performing a lot of research and then returned a synthesized report, performing a series of computations or lookups to achieve a concise, relevant answer.)
+
+Subagent lifecycle:
+1. **Spawn** → Provide clear role, instructions, and expected output
+2. **Run** → The subagent completes the task autonomously
+3. **Return** → The subagent provides a single structured result
+4. **Reconcile** → Incorporate or synthesize the result into the main thread
+
+When NOT to use the task tool:
+- If you need to see the intermediate reasoning or steps after the subagent has completed (the task tool hides them)
+- If the task is trivial (a few tool calls or simple lookup)
+- If delegating does not reduce token usage, complexity, or context switching
+- If splitting would add latency without benefit
+
+## Important Task Tool Usage Notes to Remember
+- Whenever possible, parallelize the work that you do. This is true for both tool_calls, and for tasks. Whenever you have independent steps to complete - make tool_calls, or kick off tasks (subagents) in parallel to accomplish them faster. This saves time for the user, which is incredibly important.
+- Remember to use the \`task\` tool to silo independent tasks within a multi-part objective.
+- You should use the \`task\` tool whenever you have a complex task that will take multiple steps, and is independent from other tasks that the agent needs to complete. These agents are highly competent and efficient.`;
+/**
+* Filter state to exclude certain keys when passing to subagents
+*/
+function filterStateForSubagent(state) {
+	const filtered = {};
+	for (const [key, value] of Object.entries(state)) if (!EXCLUDED_STATE_KEYS.includes(key)) filtered[key] = value;
+	return filtered;
+}
+/**
+* Create Command with filtered state update from subagent result
+*/
+function returnCommandWithStateUpdate(result, toolCallId) {
+	const stateUpdate = filterStateForSubagent(result);
+	const messages = result.messages;
+	const lastMessage = messages?.[messages.length - 1];
+	return new Command({ update: {
+		...stateUpdate,
+		messages: [new ToolMessage({
+			content: lastMessage?.content || "Task completed",
+			tool_call_id: toolCallId,
+			name: "task"
+		})]
+	} });
+}
+/**
+* Create subagent instances from specifications
+*/
+function getSubagents(options) {
+	const { defaultModel, defaultTools, defaultMiddleware, defaultInterruptOn, subagents, generalPurposeAgent } = options;
+	const defaultSubagentMiddleware = defaultMiddleware || [];
+	const agents = {};
+	const subagentDescriptions = [];
+	if (generalPurposeAgent) {
+		const generalPurposeMiddleware = [...defaultSubagentMiddleware];
+		if (defaultInterruptOn) generalPurposeMiddleware.push(humanInTheLoopMiddleware({ interruptOn: defaultInterruptOn }));
+		agents["general-purpose"] = createAgent({
+			model: defaultModel,
+			systemPrompt: DEFAULT_SUBAGENT_PROMPT,
+			tools: defaultTools,
+			middleware: generalPurposeMiddleware
+		});
+		subagentDescriptions.push(`- general-purpose: ${DEFAULT_GENERAL_PURPOSE_DESCRIPTION}`);
+	}
+	for (const agentParams of subagents) {
+		subagentDescriptions.push(`- ${agentParams.name}: ${agentParams.description}`);
+		const middleware = agentParams.middleware ? [...defaultSubagentMiddleware, ...agentParams.middleware] : [...defaultSubagentMiddleware];
+		const interruptOn = agentParams.interruptOn || defaultInterruptOn;
+		if (interruptOn) middleware.push(humanInTheLoopMiddleware({ interruptOn }));
+		agents[agentParams.name] = createAgent({
+			model: agentParams.model ?? defaultModel,
+			systemPrompt: agentParams.systemPrompt,
+			tools: agentParams.tools ?? defaultTools,
+			middleware,
+			checkpointer: false
+		});
+	}
+	return {
+		agents,
+		descriptions: subagentDescriptions
+	};
+}
+/**
+* Create the task tool for invoking subagents
+*/
+function createTaskTool(options) {
+	const { defaultModel, defaultTools, defaultMiddleware, defaultInterruptOn, subagents, generalPurposeAgent, taskDescription } = options;
+	const { agents: subagentGraphs, descriptions: subagentDescriptions } = getSubagents({
+		defaultModel,
+		defaultTools,
+		defaultMiddleware,
+		defaultInterruptOn,
+		subagents,
+		generalPurposeAgent
+	});
+	return tool(async (input, config) => {
+		const { description, subagent_type } = input;
+		if (!(subagent_type in subagentGraphs)) {
+			const allowedTypes = Object.keys(subagentGraphs).map((k) => `\`${k}\``).join(", ");
+			throw new Error(`Error: invoked agent of type ${subagent_type}, the only allowed types are ${allowedTypes}`);
+		}
+		const subagent = subagentGraphs[subagent_type];
+		const subagentState = filterStateForSubagent(getCurrentTaskInput());
+		subagentState.messages = [new HumanMessage({ content: description })];
+		const result = await subagent.invoke(subagentState);
+		if (!config.toolCall?.id) throw new Error("Tool call ID is required for subagent invocation");
+		return returnCommandWithStateUpdate(result, config.toolCall.id);
+	}, {
+		name: "task",
+		description: taskDescription ? taskDescription : getTaskToolDescription(subagentDescriptions),
+		schema: z.object({
+			description: z.string().describe("The task to execute with the selected agent"),
+			subagent_type: z.string().describe(`Name of the agent to use. Available: ${Object.keys(subagentGraphs).join(", ")}`)
+		})
+	});
+}
+/**
+* Create subagent middleware with task tool
+*/
+function createSubAgentMiddleware(options) {
+	const { defaultModel, defaultTools = [], defaultMiddleware = null, defaultInterruptOn = null, subagents = [], systemPrompt = TASK_SYSTEM_PROMPT, generalPurposeAgent = true, taskDescription = null } = options;
+	return createMiddleware({
+		name: "subAgentMiddleware",
+		tools: [createTaskTool({
+			defaultModel,
+			defaultTools,
+			defaultMiddleware,
+			defaultInterruptOn,
+			subagents,
+			generalPurposeAgent,
+			taskDescription
+		})],
+		wrapModelCall: async (request, handler) => {
+			if (systemPrompt !== null) {
+				const currentPrompt = request.systemPrompt || "";
+				const newPrompt = currentPrompt ? `${currentPrompt}\n\n${systemPrompt}` : systemPrompt;
+				return handler({
+					...request,
+					systemPrompt: newPrompt
+				});
+			}
+			return handler(request);
+		}
+	});
+}
+
+//#endregion
+//#region src/middleware/patch_tool_calls.ts
+/**
+* Create middleware that patches dangling tool calls in the messages history.
+*
+* When an AI message contains tool_calls but subsequent messages don't include
+* the corresponding ToolMessage responses, this middleware adds synthetic
+* ToolMessages saying the tool call was cancelled.
+*
+* @returns AgentMiddleware that patches dangling tool calls
+*
+* @example
+* ```typescript
+* import { createAgent } from "langchain";
+* import { createPatchToolCallsMiddleware } from "./middleware/patch_tool_calls";
+*
+* const agent = createAgent({
+*   model: "claude-sonnet-4-5-20250929",
+*   middleware: [createPatchToolCallsMiddleware()],
+* });
+* ```
+*/
+function createPatchToolCallsMiddleware() {
+	return createMiddleware({
+		name: "patchToolCallsMiddleware",
+		beforeAgent: async (state) => {
+			const messages = state.messages;
+			if (!messages || messages.length === 0) return;
+			const patchedMessages = [];
+			for (let i = 0; i < messages.length; i++) {
+				const msg = messages[i];
+				patchedMessages.push(msg);
+				if (AIMessage.isInstance(msg) && msg.tool_calls != null) {
+					for (const toolCall of msg.tool_calls) if (!messages.slice(i).find((m) => ToolMessage.isInstance(m) && m.tool_call_id === toolCall.id)) {
+						const toolMsg = `Tool call ${toolCall.name} with id ${toolCall.id} was cancelled - another message came in before it could be completed.`;
+						patchedMessages.push(new ToolMessage({
+							content: toolMsg,
+							name: toolCall.name,
+							tool_call_id: toolCall.id
+						}));
+					}
+				}
+			}
+			return { messages: [new RemoveMessage({ id: REMOVE_ALL_MESSAGES }), ...patchedMessages] };
+		}
+	});
+}
+
+//#endregion
+//#region src/agent.ts
+const BASE_PROMPT = `In order to complete the objective that the user asks of you, you have access to a number of standard tools.`;
+/**
+* Create a Deep Agent with middleware-based architecture.
+*
+* Matches Python's create_deep_agent function, using middleware for all features:
+* - Todo management (todoListMiddleware)
+* - Filesystem tools (createFilesystemMiddleware)
+* - Subagent delegation (createSubAgentMiddleware)
+* - Conversation summarization (summarizationMiddleware)
+* - Prompt caching (anthropicPromptCachingMiddleware)
+* - Tool call patching (createPatchToolCallsMiddleware)
+* - Human-in-the-loop (humanInTheLoopMiddleware) - optional
+*
+* @param params Configuration parameters for the agent
+* @returns ReactAgent instance ready for invocation
+*/
+function createDeepAgent(params = {}) {
+	const { model = "claude-sonnet-4-5-20250929", tools = [], systemPrompt, middleware: customMiddleware = [], subagents = [], responseFormat, contextSchema, checkpointer, store, useLongtermMemory = false, interruptOn, name } = params;
+	const finalSystemPrompt = systemPrompt ? `${systemPrompt}\n\n${BASE_PROMPT}` : BASE_PROMPT;
+	const middleware = [
+		todoListMiddleware(),
+		createFilesystemMiddleware({ longTermMemory: useLongtermMemory }),
+		createSubAgentMiddleware({
+			defaultModel: model,
+			defaultTools: tools,
+			defaultMiddleware: [
+				todoListMiddleware(),
+				createFilesystemMiddleware({ longTermMemory: useLongtermMemory }),
+				summarizationMiddleware({
+					model,
+					maxTokensBeforeSummary: 17e4,
+					messagesToKeep: 6
+				}),
+				anthropicPromptCachingMiddleware({ unsupportedModelBehavior: "ignore" }),
+				createPatchToolCallsMiddleware()
+			],
+			defaultInterruptOn: interruptOn,
+			subagents,
+			generalPurposeAgent: true
+		}),
+		summarizationMiddleware({
+			model,
+			maxTokensBeforeSummary: 17e4,
+			messagesToKeep: 6
+		}),
+		anthropicPromptCachingMiddleware({ unsupportedModelBehavior: "ignore" }),
+		createPatchToolCallsMiddleware()
+	];
+	if (interruptOn) middleware.push(humanInTheLoopMiddleware({ interruptOn }));
+	middleware.push(...customMiddleware);
+	return createAgent({
+		model,
+		systemPrompt: finalSystemPrompt,
+		tools,
+		middleware,
+		responseFormat,
+		contextSchema,
+		checkpointer,
+		store,
+		name
+	});
+}
+
+//#endregion
+export { createFilesystemMiddleware as FilesystemMiddleware, createFilesystemMiddleware, createDeepAgent, createPatchToolCallsMiddleware, createSubAgentMiddleware };