deepagents 1.6.1 → 1.6.3

package/dist/index.cjs

@@ -193,8 +193,14 @@ function formatReadResponse(fileData, offset, limit) {
 * @param newString - Replacement string
 * @param replaceAll - Whether to replace all occurrences
 * @returns Tuple of [new_content, occurrences] on success, or error message string
+*
+* Special case: When both content and oldString are empty, this sets the initial
+* content to newString. This allows editing empty files by treating empty oldString
+* as "set initial content" rather than "replace nothing".
 */
 function performStringReplacement(content, oldString, newString, replaceAll) {
+	if (content === "" && oldString === "") return [newString, 0];
+	if (oldString === "") return "Error: oldString cannot be empty when file has content";
 	const occurrences = content.split(oldString).length - 1;
 	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.`;
@@ -557,6 +563,18 @@ const TOOLS_EXCLUDED_FROM_EVICTION = [
 */
 const NUM_CHARS_PER_TOKEN = 4;
 /**
+* Default values for read_file tool pagination (in lines).
+*/
+const DEFAULT_READ_LINE_OFFSET = 0;
+const DEFAULT_READ_LINE_LIMIT = 100;
+/**
+* Template for truncation message in read_file.
+* {file_path} will be filled in at runtime.
+*/
+const READ_FILE_TRUNCATION_MSG = `
+
+[Output was truncated due to size limits. The file content is very large. Consider reformatting the file to make it easier to navigate. For example, if this is JSON, use execute(command='jq . {file_path}') to pretty-print it with line breaks. For other formats, you can use appropriate formatting tools to split long lines.]`;
+/**
 * Message template for evicted tool results.
 */
 const TOO_LARGE_TOOL_MSG = `Tool result too large, the result of this tool call {tool_call_id} was saved in the filesystem at this path: {file_path}
@@ -661,7 +679,7 @@ const READ_FILE_TOOL_DESCRIPTION = `Reads a file from the filesystem.
 Assume this tool is able to read all files. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
 
 Usage:
-- By default, it reads up to 500 lines starting from the beginning of the file
+- By default, it reads up to 100 lines starting from the beginning of the file
 - **IMPORTANT for large files and codebase exploration**: Use pagination with offset and limit parameters to avoid context overflow
   - First scan: read_file(path, limit=100) to see file structure
   - Read more sections: read_file(path, offset=100, limit=200) for next 200 lines
@@ -781,21 +799,29 @@ function createLsTool(backend, options) {
 * Create read_file tool using backend.
 */
 function createReadFileTool(backend, options) {
-	const { customDescription } = options;
+	const { customDescription, toolTokenLimitBeforeEvict } = options;
 	return (0, langchain.tool)(async (input, config) => {
 		const resolvedBackend = getBackend(backend, {
 			state: (0, _langchain_langgraph.getCurrentTaskInput)(config),
 			store: config.store
 		});
-		const { file_path, offset = 0, limit = 500 } = input;
-		return await resolvedBackend.read(file_path, offset, limit);
+		const { file_path, offset = DEFAULT_READ_LINE_OFFSET, limit = DEFAULT_READ_LINE_LIMIT } = input;
+		let result = await resolvedBackend.read(file_path, offset, limit);
+		const lines = result.split("\n");
+		if (lines.length > limit) result = lines.slice(0, limit).join("\n");
+		if (toolTokenLimitBeforeEvict && result.length >= NUM_CHARS_PER_TOKEN * toolTokenLimitBeforeEvict) {
+			const truncationMsg = READ_FILE_TRUNCATION_MSG.replace("{file_path}", file_path);
+			const maxContentLength = NUM_CHARS_PER_TOKEN * toolTokenLimitBeforeEvict - truncationMsg.length;
+			result = result.substring(0, maxContentLength) + truncationMsg;
+		}
+		return result;
 	}, {
 		name: "read_file",
 		description: customDescription || READ_FILE_TOOL_DESCRIPTION,
 		schema: zod_v4.z.object({
 			file_path: zod_v4.z.string().describe("Absolute path to the file to read"),
-			offset: zod_v4.z.coerce.number().optional().default(0).describe("Line offset to start reading from (0-indexed)"),
-			limit: zod_v4.z.coerce.number().optional().default(500).describe("Maximum number of lines to read")
+			offset: zod_v4.z.coerce.number().optional().default(DEFAULT_READ_LINE_OFFSET).describe("Line offset to start reading from (0-indexed)"),
+			limit: zod_v4.z.coerce.number().optional().default(DEFAULT_READ_LINE_LIMIT).describe("Maximum number of lines to read")
 		})
 	});
 }
@@ -960,7 +986,10 @@ function createFilesystemMiddleware(options = {}) {
 		stateSchema: FilesystemStateSchema,
 		tools: [
 			createLsTool(backend, { customDescription: customToolDescriptions?.ls }),
-			createReadFileTool(backend, { customDescription: customToolDescriptions?.read_file }),
+			createReadFileTool(backend, {
+				customDescription: customToolDescriptions?.read_file,
+				toolTokenLimitBeforeEvict
+			}),
 			createWriteFileTool(backend, { customDescription: customToolDescriptions?.write_file }),
 			createEditFileTool(backend, { customDescription: customToolDescriptions?.edit_file }),
 			createGlobTool(backend, { customDescription: customToolDescriptions?.glob }),
@@ -1324,12 +1353,52 @@ function createSubAgentMiddleware(options) {
 //#endregion
 //#region src/middleware/patch_tool_calls.ts
 /**
+* Patch dangling tool calls in a messages array.
+* Returns the patched messages array and a flag indicating if patching was needed.
+*
+* @param messages - The messages array to patch
+* @returns Object with patched messages and needsPatch flag
+*/
+function patchDanglingToolCalls(messages) {
+	if (!messages || messages.length === 0) return {
+		patchedMessages: [],
+		needsPatch: false
+	};
+	const patchedMessages = [];
+	let needsPatch = false;
+	for (let i = 0; i < messages.length; i++) {
+		const msg = messages[i];
+		patchedMessages.push(msg);
+		if (langchain.AIMessage.isInstance(msg) && msg.tool_calls != null) {
+			for (const toolCall of msg.tool_calls) if (!messages.slice(i).find((m) => langchain.ToolMessage.isInstance(m) && m.tool_call_id === toolCall.id)) {
+				needsPatch = true;
+				const toolMsg = `Tool call ${toolCall.name} with id ${toolCall.id} was cancelled - another message came in before it could be completed.`;
+				patchedMessages.push(new langchain.ToolMessage({
+					content: toolMsg,
+					name: toolCall.name,
+					tool_call_id: toolCall.id
+				}));
+			}
+		}
+	}
+	return {
+		patchedMessages,
+		needsPatch
+	};
+}
+/**
 * 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.
 *
+* This middleware patches in two places:
+* 1. `beforeAgent`: Patches state at the start of the agent loop (handles most cases)
+* 2. `wrapModelCall`: Patches the request right before model invocation (handles
+*    edge cases like HITL rejection during graph resume where state updates from
+*    beforeAgent may not be applied in time)
+*
 * @returns AgentMiddleware that patches dangling tool calls
 *
 * @example
@@ -1349,26 +1418,61 @@ function createPatchToolCallsMiddleware() {
 		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 (langchain.AIMessage.isInstance(msg) && msg.tool_calls != null) {
-					for (const toolCall of msg.tool_calls) if (!messages.slice(i).find((m) => langchain.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 langchain.ToolMessage({
-							content: toolMsg,
-							name: toolCall.name,
-							tool_call_id: toolCall.id
-						}));
-					}
-				}
-			}
+			const { patchedMessages, needsPatch } = patchDanglingToolCalls(messages);
+			/**
+			* Only trigger REMOVE_ALL_MESSAGES if patching is actually needed
+			*/
+			if (!needsPatch) return;
 			return { messages: [new _langchain_core_messages.RemoveMessage({ id: _langchain_langgraph.REMOVE_ALL_MESSAGES }), ...patchedMessages] };
+		},
+		wrapModelCall: async (request, handler) => {
+			const messages = request.messages;
+			if (!messages || messages.length === 0) return handler(request);
+			const { patchedMessages, needsPatch } = patchDanglingToolCalls(messages);
+			if (!needsPatch) return handler(request);
+			return handler({
+				...request,
+				messages: patchedMessages
+			});
 		}
 	});
 }
 
+//#endregion
+//#region src/values.ts
+/**
+* Shared state values for use in StateSchema definitions.
+*
+* This module provides pre-configured ReducedValue instances that can be
+* reused across different state schemas, similar to LangGraph's messagesValue.
+*/
+/**
+* Shared ReducedValue for file data state management.
+*
+* This provides a reusable pattern for managing file state with automatic
+* merging of concurrent updates from parallel subagents. Files can be updated
+* or deleted (using null values) and the reducer handles the merge logic.
+*
+* Similar to LangGraph's messagesValue, this encapsulates the common pattern
+* of managing files in agent state so you don't have to manually configure
+* the ReducedValue each time.
+*
+* @example
+* ```typescript
+* import { filesValue } from "@anthropic/deepagents";
+* import { StateSchema } from "@langchain/langgraph";
+*
+* const MyStateSchema = new StateSchema({
+*   files: filesValue,
+*   // ... other state fields
+* });
+* ```
+*/
+const filesValue = new _langchain_langgraph.ReducedValue(zod.z.record(zod.z.string(), FileDataSchema).default(() => ({})), {
+	inputSchema: zod.z.record(zod.z.string(), FileDataSchema.nullable()).optional(),
+	reducer: fileDataReducer
+});
+
 //#endregion
 //#region src/middleware/memory.ts
 /**
@@ -1423,7 +1527,10 @@ function createPatchToolCallsMiddleware() {
 /**
 * State schema for memory middleware.
 */
-const MemoryStateSchema = zod.z.object({ memoryContents: zod.z.record(zod.z.string(), zod.z.string()).optional() });
+const MemoryStateSchema = new _langchain_langgraph.StateSchema({
+	memoryContents: zod.z.record(zod.z.string(), zod.z.string()).optional(),
+	files: filesValue
+});
 /**
 * Default system prompt template for memory.
 * Ported from Python's comprehensive memory guidelines.
@@ -1567,12 +1674,10 @@ function createMemoryMiddleware(options) {
 		},
 		wrapModelCall(request, handler) {
 			const formattedContents = formatMemoryContents(request.state?.memoryContents || {}, sources);
-			const memorySection = MEMORY_SYSTEM_PROMPT.replace("{memory_contents}", formattedContents);
-			const currentSystemPrompt = request.systemPrompt || "";
-			const newSystemPrompt = currentSystemPrompt ? `${memorySection}\n\n${currentSystemPrompt}` : memorySection;
+			const newSystemMessage = new langchain.SystemMessage(MEMORY_SYSTEM_PROMPT.replace("{memory_contents}", formattedContents)).concat(request.systemMessage);
 			return handler({
 				...request,
-				systemPrompt: newSystemPrompt
+				systemMessage: newSystemMessage
 			});
 		}
 	});
@@ -1655,10 +1760,13 @@ function skillsMetadataReducer(current, update) {
 * State schema for skills middleware.
 * Uses ReducedValue for skillsMetadata to allow concurrent updates from parallel subagents.
 */
-const SkillsStateSchema = new _langchain_langgraph.StateSchema({ skillsMetadata: new _langchain_langgraph.ReducedValue(zod.z.array(SkillMetadataEntrySchema).default(() => []), {
-	inputSchema: zod.z.array(SkillMetadataEntrySchema).optional(),
-	reducer: skillsMetadataReducer
-}) });
+const SkillsStateSchema = new _langchain_langgraph.StateSchema({
+	skillsMetadata: new _langchain_langgraph.ReducedValue(zod.z.array(SkillMetadataEntrySchema).default(() => []), {
+		inputSchema: zod.z.array(SkillMetadataEntrySchema).optional(),
+		reducer: skillsMetadataReducer
+	}),
+	files: filesValue
+});
 /**
 * Skills System Documentation prompt template.
 */
@@ -1879,7 +1987,7 @@ function createSkillsMiddleware(options) {
 		stateSchema: SkillsStateSchema,
 		async beforeAgent(state) {
 			if (loadedSkills.length > 0) return;
-			if ("skillsMetadata" in state && state.skillsMetadata != null) {
+			if ("skillsMetadata" in state && Array.isArray(state.skillsMetadata) && state.skillsMetadata.length > 0) {
 				loadedSkills = state.skillsMetadata;
 				return;
 			}
@@ -3457,6 +3565,9 @@ const BASE_PROMPT = `In order to complete the objective that the user asks of yo
 */
 function createDeepAgent(params = {}) {
 	const { model = "claude-sonnet-4-5-20250929", tools = [], systemPrompt, middleware: customMiddleware = [], subagents = [], responseFormat, contextSchema, checkpointer, store, backend, interruptOn, name, memory, skills } = params;
+	/**
+	* Combine system prompt with base prompt like Python implementation
+	*/
 	const finalSystemPrompt = systemPrompt ? typeof systemPrompt === "string" ? `${systemPrompt}\n\n${BASE_PROMPT}` : new langchain.SystemMessage({ content: [{
 		type: "text",
 		text: BASE_PROMPT
@@ -3464,22 +3575,61 @@ function createDeepAgent(params = {}) {
 		type: "text",
 		text: systemPrompt.content
 	}] : systemPrompt.content] }) : BASE_PROMPT;
+	/**
+	* Create backend configuration for filesystem middleware
+	* If no backend is provided, use a factory that creates a StateBackend
+	*/
 	const filesystemBackend = backend ? backend : (config) => new StateBackend(config);
-	const skillsMiddleware = skills != null && skills.length > 0 ? [createSkillsMiddleware({
+	/**
+	* Skills middleware (created conditionally for runtime use)
+	*/
+	const skillsMiddlewareArray = skills != null && skills.length > 0 ? [createSkillsMiddleware({
 		backend: filesystemBackend,
 		sources: skills
 	})] : [];
-	const builtInMiddleware = [
-		(0, langchain.todoListMiddleware)(),
-		...skillsMiddleware,
-		createFilesystemMiddleware({ backend: filesystemBackend }),
-		createSubAgentMiddleware({
-			defaultModel: model,
-			defaultTools: tools,
-			defaultMiddleware: [
+	/**
+	* Memory middleware (created conditionally for runtime use)
+	*/
+	const memoryMiddlewareArray = memory != null && memory.length > 0 ? [createMemoryMiddleware({
+		backend: filesystemBackend,
+		sources: memory
+	})] : [];
+	/**
+	* Return as DeepAgent with proper DeepAgentTypeConfig
+	* - Response: TResponse (from responseFormat parameter)
+	* - State: undefined (state comes from middleware)
+	* - Context: ContextSchema
+	* - Middleware: AllMiddleware (built-in + custom + subagent middleware for state inference)
+	* - Tools: TTools
+	* - Subagents: TSubagents (for type-safe streaming)
+	*/
+	return (0, langchain.createAgent)({
+		model,
+		systemPrompt: finalSystemPrompt,
+		tools,
+		middleware: [
+			...[
 				(0, langchain.todoListMiddleware)(),
-				...skillsMiddleware,
 				createFilesystemMiddleware({ backend: filesystemBackend }),
+				createSubAgentMiddleware({
+					defaultModel: model,
+					defaultTools: tools,
+					defaultMiddleware: [
+						(0, langchain.todoListMiddleware)(),
+						...skillsMiddlewareArray,
+						createFilesystemMiddleware({ backend: filesystemBackend }),
+						(0, langchain.summarizationMiddleware)({
+							model,
+							trigger: { tokens: 17e4 },
+							keep: { messages: 6 }
+						}),
+						(0, langchain.anthropicPromptCachingMiddleware)({ unsupportedModelBehavior: "ignore" }),
+						createPatchToolCallsMiddleware()
+					],
+					defaultInterruptOn: interruptOn,
+					subagents,
+					generalPurposeAgent: true
+				}),
 				(0, langchain.summarizationMiddleware)({
 					model,
 					trigger: { tokens: 17e4 },
@@ -3488,34 +3638,17 @@ function createDeepAgent(params = {}) {
 				(0, langchain.anthropicPromptCachingMiddleware)({ unsupportedModelBehavior: "ignore" }),
 				createPatchToolCallsMiddleware()
 			],
-			defaultInterruptOn: interruptOn,
-			subagents,
-			generalPurposeAgent: true
-		}),
-		(0, langchain.summarizationMiddleware)({
-			model,
-			trigger: { tokens: 17e4 },
-			keep: { messages: 6 }
-		}),
-		(0, langchain.anthropicPromptCachingMiddleware)({ unsupportedModelBehavior: "ignore" }),
-		createPatchToolCallsMiddleware(),
-		...memory != null && memory.length > 0 ? [createMemoryMiddleware({
-			backend: filesystemBackend,
-			sources: memory
-		})] : []
-	];
-	if (interruptOn) builtInMiddleware.push((0, langchain.humanInTheLoopMiddleware)({ interruptOn }));
-	return (0, langchain.createAgent)({
-		model,
-		systemPrompt: finalSystemPrompt,
-		tools,
-		middleware: [...builtInMiddleware, ...customMiddleware],
+			...skillsMiddlewareArray,
+			...memoryMiddlewareArray,
+			...interruptOn ? [(0, langchain.humanInTheLoopMiddleware)({ interruptOn })] : [],
+			...customMiddleware
+		],
 		responseFormat,
 		contextSchema,
 		checkpointer,
 		store,
 		name
-	});
+	}).withConfig({ recursionLimit: 1e4 });
 }
 
 //#endregion
@@ -4079,6 +4212,7 @@ exports.createPatchToolCallsMiddleware = createPatchToolCallsMiddleware;
 exports.createSettings = createSettings;
 exports.createSkillsMiddleware = createSkillsMiddleware;
 exports.createSubAgentMiddleware = createSubAgentMiddleware;
+exports.filesValue = filesValue;
 exports.findProjectRoot = findProjectRoot;
 exports.isSandboxBackend = isSandboxBackend;
 exports.listSkills = listSkills;