deepagents 1.8.0 → 1.8.2

package/README.md

@@ -1,9 +1,9 @@
 <div align="center">
   <a href="https://docs.langchain.com/oss/python/deepagents/overview#deep-agents-overview">
     <picture>
-      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/langchain-ai/deepagentsjs/refs/heads/main/.github/images/logo-dark.svg">
-      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/langchain-ai/deepagentsjs/refs/heads/main/.github/images/logo-light.svg">
-      <img alt="Deep Agents Logo" src="https://raw.githubusercontent.com/langchain-ai/deepagentsjs/refs/heads/main/.github/images/logo-dark.svg" width="80%">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/langchain-ai/deepagentsjs/refs/heads/main/.github/images/logo-light.svg">
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/langchain-ai/deepagentsjs/refs/heads/main/.github/images/logo-dark.svg">
+      <img alt="Deep Agents Logo" src="https://raw.githubusercontent.com/langchain-ai/deepagentsjs/refs/heads/main/.github/images/logo-dark.svg" width="50%">
     </picture>
   </a>
 </div>
@@ -132,6 +132,9 @@ const researchInstructions = `You are an expert researcher. Your job is to condu
 
 You have access to an internet search tool as your primary means of gathering information.
 
+> [!TIP]
+> For developing, debugging, and deploying AI agents and LLM applications, see [LangSmith](https://docs.langchain.com/langsmith/home).
+
 ## \`internet_search\`
 
 Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
@@ -713,3 +716,52 @@ const agent = createAgent({
   ],
 });
 ```
+
+## ACP (Agent Client Protocol) Support
+
+Deep Agents can be exposed as an [Agent Client Protocol](https://agentclientprotocol.com) server, enabling integration with IDEs like [Zed](https://zed.dev), JetBrains, and other ACP-compatible clients through a standardized JSON-RPC 2.0 protocol over stdio.
+
+The `deepagents-acp` package wraps your Deep Agent with ACP support:
+
+```bash
+npm install deepagents-acp
+```
+
+The quickest way to get started is via the CLI:
+
+```bash
+npx deepagents-acp --name my-agent --workspace /path/to/project
+```
+
+Or programmatically:
+
+```typescript
+import { startServer } from "deepagents-acp";
+
+await startServer({
+  agents: {
+    name: "coding-assistant",
+    description: "AI coding assistant with filesystem access",
+    skills: ["./skills/"],
+  },
+  workspaceRoot: process.cwd(),
+});
+```
+
+To use with Zed, add the following to your Zed settings:
+
+```json
+{
+  "agent": {
+    "profiles": {
+      "deepagents": {
+        "name": "DeepAgents",
+        "command": "npx",
+        "args": ["deepagents-acp"]
+      }
+    }
+  }
+}
+```
+
+See the [deepagents-acp README](libs/acp/README.md) and the [ACP server example](examples/acp-server/) for full documentation and advanced configuration.

package/dist/index.cjs

@@ -125,6 +125,8 @@ var SandboxError = class SandboxError extends Error {
 const EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents";
 const MAX_LINE_LENGTH = 1e4;
 const LINE_NUMBER_WIDTH = 6;
+const TOOL_RESULT_TOKEN_LIMIT = 2e4;
+const TRUNCATION_GUIDANCE = "... [results truncated, try being more specific with your parameters]";
 /**
 * Sanitize tool_call_id to prevent path traversal and separator issues.
 *
@@ -260,6 +262,21 @@ function performStringReplacement(content, oldString, newString, replaceAll) {
 	return [content.split(oldString).join(newString), occurrences];
 }
 /**
+* Truncate list or string result if it exceeds token limit (rough estimate: 4 chars/token).
+*/
+function truncateIfTooLong(result) {
+	if (Array.isArray(result)) {
+		const totalChars = result.reduce((sum, item) => sum + item.length, 0);
+		if (totalChars > TOOL_RESULT_TOKEN_LIMIT * 4) {
+			const truncateAt = Math.floor(result.length * TOOL_RESULT_TOKEN_LIMIT * 4 / totalChars);
+			return [...result.slice(0, truncateAt), TRUNCATION_GUIDANCE];
+		}
+		return result;
+	}
+	if (result.length > TOOL_RESULT_TOKEN_LIMIT * 4) return result.substring(0, TOOL_RESULT_TOKEN_LIMIT * 4) + "\n... [results truncated, try being more specific with your parameters]";
+	return result;
+}
+/**
 * Validate and normalize a directory path.
 *
 * Ensures paths are safe to use by preventing directory traversal attacks
@@ -839,7 +856,9 @@ function createLsTool(backend, options) {
 			const size = info.size ? ` (${info.size} bytes)` : "";
 			lines.push(`${info.path}${size}`);
 		}
-		return lines.join("\n");
+		const result = truncateIfTooLong(lines);
+		if (Array.isArray(result)) return result.join("\n");
+		return result;
 	}, {
 		name: "ls",
 		description: customDescription || LS_TOOL_DESCRIPTION,
@@ -957,7 +976,9 @@ function createGlobTool(backend, options) {
 		const { pattern, path = "/" } = input;
 		const infos = await resolvedBackend.globInfo(pattern, path);
 		if (infos.length === 0) return `No files found matching pattern '${pattern}'`;
-		return infos.map((info) => info.path).join("\n");
+		const result = truncateIfTooLong(infos.map((info) => info.path));
+		if (Array.isArray(result)) return result.join("\n");
+		return result;
 	}, {
 		name: "glob",
 		description: customDescription || GLOB_TOOL_DESCRIPTION,
@@ -990,7 +1011,9 @@ function createGrepTool(backend, options) {
 			}
 			lines.push(`  ${match.line}: ${match.text}`);
 		}
-		return lines.join("\n");
+		const truncated = truncateIfTooLong(lines);
+		if (Array.isArray(truncated)) return truncated.join("\n");
+		return truncated;
 	}, {
 		name: "grep",
 		description: customDescription || GREP_TOOL_DESCRIPTION,
@@ -1085,7 +1108,13 @@ function createFilesystemMiddleware(options = {}) {
 						message: new langchain.ToolMessage({
 							content: TOO_LARGE_TOOL_MSG.replace("{tool_call_id}", msg.tool_call_id).replace("{file_path}", evictPath).replace("{content_sample}", contentSample),
 							tool_call_id: msg.tool_call_id,
-							name: msg.name
+							name: msg.name,
+							id: msg.id,
+							artifact: msg.artifact,
+							status: msg.status,
+							metadata: msg.metadata,
+							additional_kwargs: msg.additional_kwargs,
+							response_metadata: msg.response_metadata
 						}),
 						filesUpdate: writeResult.filesUpdate
 					};
@@ -1363,16 +1392,28 @@ function filterStateForSubagent(state) {
 	return filtered;
 }
 /**
+* Invalid tool message block types
+*/
+const INVALID_TOOL_MESSAGE_BLOCK_TYPES = [
+	"tool_use",
+	"thinking",
+	"redacted_thinking"
+];
+/**
 * 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];
+	let content = (messages?.[messages.length - 1])?.content || "Task completed";
+	if (Array.isArray(content)) {
+		content = content.filter((block) => !INVALID_TOOL_MESSAGE_BLOCK_TYPES.includes(block.type));
+		if (content.length === 0) content = "Task completed";
+	}
 	return new _langchain_langgraph.Command({ update: {
 		...stateUpdate,
 		messages: [new langchain.ToolMessage({
-			content: lastMessage?.content || "Task completed",
+			content,
 			tool_call_id: toolCallId,
 			name: "task"
 		})]
@@ -1444,7 +1485,16 @@ function createTaskTool(options) {
 		const subagentState = filterStateForSubagent((0, _langchain_langgraph.getCurrentTaskInput)());
 		subagentState.messages = [new _langchain_core_messages.HumanMessage({ content: description })];
 		const result = await subagent.invoke(subagentState, config);
-		if (!config.toolCall?.id) throw new Error("Tool call ID is required for subagent invocation");
+		if (!config.toolCall?.id) {
+			const messages = result.messages;
+			let content = (messages?.[messages.length - 1])?.content || "Task completed";
+			if (Array.isArray(content)) {
+				content = content.filter((block) => !INVALID_TOOL_MESSAGE_BLOCK_TYPES.includes(block.type));
+				if (content.length === 0) return "Task completed";
+				return content.map((block) => "text" in block ? block.text : JSON.stringify(block)).join("\n");
+			}
+			return content;
+		}
 		return returnCommandWithStateUpdate(result, config.toolCall.id);
 	}, {
 		name: "task",
@@ -1781,7 +1831,7 @@ async function loadMemoryFromBackend(backend, path) {
 * ```
 */
 function createMemoryMiddleware(options) {
-	const { backend, sources } = options;
+	const { backend, sources, addCacheControl = false } = options;
 	/**
 	* Resolve backend from instance or factory.
 	*/
@@ -1806,7 +1856,16 @@ function createMemoryMiddleware(options) {
 		},
 		wrapModelCall(request, handler) {
 			const formattedContents = formatMemoryContents(request.state?.memoryContents || {}, sources);
-			const newSystemMessage = new langchain.SystemMessage(MEMORY_SYSTEM_PROMPT.replace("{memory_contents}", formattedContents)).concat(request.systemMessage);
+			const memorySection = MEMORY_SYSTEM_PROMPT.replace("{memory_contents}", formattedContents);
+			const existingContent = request.systemMessage.content;
+			const newSystemMessage = new langchain.SystemMessage({ content: [...typeof existingContent === "string" ? [{
+				type: "text",
+				text: existingContent
+			}] : Array.isArray(existingContent) ? existingContent : [], {
+				type: "text",
+				text: memorySection,
+				...addCacheControl && { cache_control: { type: "ephemeral" } }
+			}] });
 			return handler({
 				...request,
 				systemMessage: newSystemMessage
@@ -2702,31 +2761,44 @@ function createSummarizationMiddleware(options) {
 		return messages.filter((msg) => !isSummaryMessage(msg));
 	}
 	/**
-	* Offload messages to backend.
+	* Offload messages to backend by appending to the history file.
+	*
+	* Uses uploadFiles() directly with raw byte concatenation instead of
+	* edit() to avoid downloading the file twice and performing a full
+	* string search-and-replace. This keeps peak memory at ~2x file size
+	* (existing bytes + combined bytes) instead of ~6x with the old
+	* download → edit(oldContent, newContent) approach.
 	*/
 	async function offloadToBackend(resolvedBackend, messages, state) {
-		const path = getHistoryPath(state);
+		const filePath = getHistoryPath(state);
 		const filteredMessages = filterSummaryMessages(messages);
 		const newSection = `## Summarized at ${(/* @__PURE__ */ new Date()).toISOString()}\n\n${(0, _langchain_core_messages.getBufferString)(filteredMessages)}\n\n`;
-		let existingContent = "";
-		try {
-			if (resolvedBackend.downloadFiles) {
-				const responses = await resolvedBackend.downloadFiles([path]);
-				if (responses.length > 0 && responses[0].content && !responses[0].error) existingContent = new TextDecoder().decode(responses[0].content);
-			}
-		} catch {}
-		const combinedContent = existingContent + newSection;
+		const sectionBytes = new TextEncoder().encode(newSection);
 		try {
+			let existingBytes = null;
+			if (resolvedBackend.downloadFiles) try {
+				const responses = await resolvedBackend.downloadFiles([filePath]);
+				if (responses.length > 0 && responses[0].content && !responses[0].error) existingBytes = responses[0].content;
+			} catch {}
 			let result;
-			if (existingContent) result = await resolvedBackend.edit(path, existingContent, combinedContent);
-			else result = await resolvedBackend.write(path, combinedContent);
+			if (existingBytes && resolvedBackend.uploadFiles) {
+				const combined = new Uint8Array(existingBytes.byteLength + sectionBytes.byteLength);
+				combined.set(existingBytes, 0);
+				combined.set(sectionBytes, existingBytes.byteLength);
+				const uploadResults = await resolvedBackend.uploadFiles([[filePath, combined]]);
+				result = uploadResults[0].error ? { error: uploadResults[0].error } : { path: filePath };
+			} else if (!existingBytes) result = await resolvedBackend.write(filePath, newSection);
+			else {
+				const existingContent = new TextDecoder().decode(existingBytes);
+				result = await resolvedBackend.edit(filePath, existingContent, existingContent + newSection);
+			}
 			if (result.error) {
-				console.warn(`Failed to offload conversation history to ${path}: ${result.error}`);
+				console.warn(`Failed to offload conversation history to ${filePath}: ${result.error}`);
 				return null;
 			}
-			return path;
+			return filePath;
 		} catch (e) {
-			console.warn(`Exception offloading conversation history to ${path}:`, e);
+			console.warn(`Exception offloading conversation history to ${filePath}:`, e);
 			return null;
 		}
 	}
@@ -2804,9 +2876,10 @@ ${summary}
 	*/
 	function isContextOverflow(err) {
 		let cause = err;
-		while (cause != null) {
+		for (;;) {
+			if (!cause) break;
 			if (_langchain_core_errors.ContextOverflowError.isInstance(cause)) return true;
-			cause = typeof cause === "object" && cause !== null && "cause" in cause ? cause.cause : void 0;
+			cause = typeof cause === "object" && "cause" in cause ? cause.cause : void 0;
 		}
 		return false;
 	}
@@ -2916,18 +2989,43 @@ ${summary}
 
 //#endregion
 //#region src/backends/store.ts
+const NAMESPACE_COMPONENT_RE = /^[A-Za-z0-9\-_.@+:~]+$/;
+/**
+* Validate a namespace array.
+*
+* Each component must be a non-empty string containing only safe characters:
+* alphanumeric (a-z, A-Z, 0-9), hyphen (-), underscore (_), dot (.),
+* at sign (@), plus (+), colon (:), and tilde (~).
+*
+* Characters like *, ?, [, ], {, } etc. are rejected to prevent
+* wildcard or glob injection in store lookups.
+*/
+function validateNamespace(namespace) {
+	if (namespace.length === 0) throw new Error("Namespace array must not be empty.");
+	for (let i = 0; i < namespace.length; i++) {
+		const component = namespace[i];
+		if (typeof component !== "string") throw new TypeError(`Namespace component at index ${i} must be a string, got ${typeof component}.`);
+		if (!component) throw new Error(`Namespace component at index ${i} must not be empty.`);
+		if (!NAMESPACE_COMPONENT_RE.test(component)) throw new Error(`Namespace component at index ${i} contains disallowed characters: "${component}". Only alphanumeric characters, hyphens, underscores, dots, @, +, colons, and tildes are allowed.`);
+	}
+	return namespace;
+}
 /**
 * Backend that stores files in LangGraph's BaseStore (persistent).
 *
 * Uses LangGraph's Store for persistent, cross-conversation storage.
 * Files are organized via namespaces and persist across all threads.
 *
-* The namespace can include an optional assistant_id for multi-agent isolation.
+* The namespace can be customized via a factory function for flexible
+* isolation patterns (user-scoped, org-scoped, etc.), or falls back
+* to legacy assistant_id-based isolation.
 */
 var StoreBackend = class {
 	stateAndStore;
-	constructor(stateAndStore) {
+	_namespace;
+	constructor(stateAndStore, options) {
 		this.stateAndStore = stateAndStore;
+		if (options?.namespace) this._namespace = validateNamespace(options.namespace);
 	}
 	/**
 	* Get the store instance.
@@ -2943,15 +3041,17 @@ var StoreBackend = class {
 	/**
 	* Get the namespace for store operations.
 	*
-	* If an assistant_id is available in stateAndStore, return
-	* [assistant_id, "filesystem"] to provide per-assistant isolation.
-	* Otherwise return ["filesystem"].
+	* If a custom namespace was provided, returns it directly.
+	*
+	* Otherwise, falls back to legacy behavior:
+	* - If assistantId is set: [assistantId, "filesystem"]
+	* - Otherwise: ["filesystem"]
 	*/
 	getNamespace() {
-		const namespace = "filesystem";
+		if (this._namespace) return this._namespace;
 		const assistantId = this.stateAndStore.assistantId;
-		if (assistantId) return [assistantId, namespace];
-		return [namespace];
+		if (assistantId) return [assistantId, "filesystem"];
+		return ["filesystem"];
 	}
 	/**
 	* Convert a store Item to FileData format.
@@ -3770,6 +3870,10 @@ var CompositeBackend = class {
 		this.routes = routes;
 		this.sortedRoutes = Object.entries(routes).sort((a, b) => b[0].length - a[0].length);
 	}
+	/** Delegates to default backend's id if it is a sandbox, otherwise empty string. */
+	get id() {
+		return isSandboxBackend(this.default) ? this.default.id : "";
+	}
 	/**
 	* Determine which backend handles this key and strip prefix.
 	*
@@ -4611,17 +4715,85 @@ var BaseSandbox = class {
 	*
 	* Uses downloadFiles() to read, performs string replacement in TypeScript,
 	* then uploadFiles() to write back. No runtime needed on the sandbox host.
+	*
+	* Memory-conscious: releases intermediate references early so the GC can
+	* reclaim buffers before the next large allocation is made.
 	*/
 	async edit(filePath, oldString, newString, replaceAll = false) {
 		const results = await this.downloadFiles([filePath]);
 		if (results[0].error || !results[0].content) return { error: `Error: File '${filePath}' not found` };
 		const text = new TextDecoder().decode(results[0].content);
-		const count = text.split(oldString).length - 1;
-		if (count === 0) return { error: `String not found in file '${filePath}'` };
-		if (count > 1 && !replaceAll) return { error: `Multiple occurrences found in '${filePath}'. Use replaceAll=true to replace all.` };
-		const newText = replaceAll ? text.split(oldString).join(newString) : text.replace(oldString, newString);
-		const encoder = new TextEncoder();
-		const uploadResults = await this.uploadFiles([[filePath, encoder.encode(newText)]]);
+		results[0].content = null;
+		/**
+		* are we editing an empty file?
+		*/
+		if (oldString.length === 0) {
+			/**
+			* if the file is not empty, we cannot edit it with an empty oldString
+			*/
+			if (text.length !== 0) return { error: "oldString must not be empty unless the file is empty" };
+			/**
+			* if the newString is empty, we can just return the file as is
+			*/
+			if (newString.length === 0) return {
+				path: filePath,
+				filesUpdate: null,
+				occurrences: 0
+			};
+			/**
+			* if the newString is not empty, we can edit the file
+			*/
+			const encoded = new TextEncoder().encode(newString);
+			const uploadResults = await this.uploadFiles([[filePath, encoded]]);
+			/**
+			* if the upload fails, we return an error
+			*/
+			if (uploadResults[0].error) return { error: `Failed to write edited file '${filePath}': ${uploadResults[0].error}` };
+			return {
+				path: filePath,
+				filesUpdate: null,
+				occurrences: 1
+			};
+		}
+		const firstIdx = text.indexOf(oldString);
+		if (firstIdx === -1) return { error: `String not found in file '${filePath}'` };
+		if (oldString === newString) return {
+			path: filePath,
+			filesUpdate: null,
+			occurrences: 1
+		};
+		let newText;
+		let count;
+		if (replaceAll) {
+			newText = text.replaceAll(oldString, newString);
+			/**
+			* Derive count from the length delta to avoid a separate O(n) counting pass
+			*/
+			const lenDiff = oldString.length - newString.length;
+			if (lenDiff !== 0) count = (text.length - newText.length) / lenDiff;
+			else {
+				/**
+				* Lengths are equal — count via indexOf (we already found the first)
+				*/
+				count = 1;
+				let pos = firstIdx + oldString.length;
+				while (pos <= text.length) {
+					const idx = text.indexOf(oldString, pos);
+					if (idx === -1) break;
+					count++;
+					pos = idx + oldString.length;
+				}
+			}
+		} else {
+			if (text.indexOf(oldString, firstIdx + oldString.length) !== -1) return { error: `Multiple occurrences found in '${filePath}'. Use replaceAll=true to replace all.` };
+			count = 1;
+			/**
+			* Build result from the known index — avoids a redundant search by .replace()
+			*/
+			newText = text.slice(0, firstIdx) + newString + text.slice(firstIdx + oldString.length);
+		}
+		const encoded = new TextEncoder().encode(newText);
+		const uploadResults = await this.uploadFiles([[filePath, encoded]]);
 		if (uploadResults[0].error) return { error: `Failed to write edited file '${filePath}': ${uploadResults[0].error}` };
 		return {
 			path: filePath,
@@ -4631,10 +4803,66 @@ var BaseSandbox = class {
 	}
 };
 
+//#endregion
+//#region src/middleware/cache.ts
+/**
+* Creates a middleware that places a cache breakpoint at the end of the static
+* system prompt content.
+*
+* This middleware tags the last block of the system message with
+* `cache_control: { type: "ephemeral" }` at the time it runs, capturing all
+* static content injected by preceding middleware (e.g. todo list instructions,
+* filesystem tools, subagent instructions) in a single cache breakpoint.
+*
+* This should run after all static system prompt middleware and before any
+* dynamic middleware (e.g. memory) so the breakpoint sits at the boundary
+* between stable and changing content.
+*
+* When used alongside memory middleware (which adds its own breakpoint on the
+* memory block), the result is two separate cache breakpoints:
+* - One covering all static content
+* - One covering the memory block
+*
+* This is a no-op when the system message has no content blocks.
+*/
+function createCacheBreakpointMiddleware() {
+	return (0, langchain.createMiddleware)({
+		name: "CacheBreakpointMiddleware",
+		wrapModelCall(request, handler) {
+			const existingContent = request.systemMessage.content;
+			const existingBlocks = typeof existingContent === "string" ? [{
+				type: "text",
+				text: existingContent
+			}] : Array.isArray(existingContent) ? [...existingContent] : [];
+			if (existingBlocks.length === 0) return handler(request);
+			existingBlocks[existingBlocks.length - 1] = {
+				...existingBlocks[existingBlocks.length - 1],
+				cache_control: { type: "ephemeral" }
+			};
+			return handler({
+				...request,
+				systemMessage: new langchain.SystemMessage({ content: existingBlocks })
+			});
+		}
+	});
+}
+
 //#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.`;
 /**
+* Detect whether a model is an Anthropic model.
+* Used to gate Anthropic-specific prompt caching optimizations (cache_control breakpoints).
+*/
+function isAnthropicModel(model) {
+	if (typeof model === "string") {
+		if (model.includes(":")) return model.split(":")[0] === "anthropic";
+		return model.startsWith("claude");
+	}
+	if (model.getName() === "ConfigurableModel") return model._defaultConfig?.modelProvider === "anthropic";
+	return model.getName() === "ChatAnthropic";
+}
+/**
 * Create a Deep Agent with middleware-based architecture.
 *
 * Matches Python's create_deep_agent function, using middleware for all features:
@@ -4667,16 +4895,20 @@ 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: [{
+	const anthropicModel = isAnthropicModel(model);
+	const finalSystemPrompt = new langchain.SystemMessage({ content: systemPrompt ? typeof systemPrompt === "string" ? [{
+		type: "text",
+		text: `${systemPrompt}\n\n${BASE_PROMPT}`
+	}] : [{
 		type: "text",
 		text: BASE_PROMPT
 	}, ...typeof systemPrompt.content === "string" ? [{
 		type: "text",
 		text: systemPrompt.content
-	}] : systemPrompt.content] }) : BASE_PROMPT;
+	}] : systemPrompt.content] : [{
+		type: "text",
+		text: BASE_PROMPT
+	}] });
 	/**
 	* Create backend configuration for filesystem middleware
 	* If no backend is provided, use a factory that creates a StateBackend
@@ -4694,7 +4926,8 @@ function createDeepAgent(params = {}) {
 	*/
 	const memoryMiddlewareArray = memory != null && memory.length > 0 ? [createMemoryMiddleware({
 		backend: filesystemBackend,
-		sources: memory
+		sources: memory,
+		addCacheControl: anthropicModel
 	})] : [];
 	/**
 	* Process subagents to add SkillsMiddleware for those with their own skills.
@@ -4743,7 +4976,10 @@ function createDeepAgent(params = {}) {
 			model,
 			backend: filesystemBackend
 		}),
-		(0, langchain.anthropicPromptCachingMiddleware)({ unsupportedModelBehavior: "ignore" }),
+		(0, langchain.anthropicPromptCachingMiddleware)({
+			unsupportedModelBehavior: "ignore",
+			minMessagesToCache: 1
+		}),
 		createPatchToolCallsMiddleware()
 	];
 	/**
@@ -4766,8 +5002,12 @@ function createDeepAgent(params = {}) {
 				createSubAgentMiddleware({
 					defaultModel: model,
 					defaultTools: tools,
-					defaultMiddleware: subagentMiddleware,
-					generalPurposeMiddleware: [...subagentMiddleware, ...skillsMiddlewareArray],
+					defaultMiddleware: [...subagentMiddleware, ...anthropicModel ? [createCacheBreakpointMiddleware()] : []],
+					generalPurposeMiddleware: [
+						...subagentMiddleware,
+						...skillsMiddlewareArray,
+						...anthropicModel ? [createCacheBreakpointMiddleware()] : []
+					],
 					defaultInterruptOn: interruptOn,
 					subagents: processedSubagents,
 					generalPurposeAgent: true
@@ -4776,10 +5016,14 @@ function createDeepAgent(params = {}) {
 					model,
 					backend: filesystemBackend
 				}),
-				(0, langchain.anthropicPromptCachingMiddleware)({ unsupportedModelBehavior: "ignore" }),
+				(0, langchain.anthropicPromptCachingMiddleware)({
+					unsupportedModelBehavior: "ignore",
+					minMessagesToCache: 1
+				}),
 				createPatchToolCallsMiddleware()
 			],
 			...skillsMiddlewareArray,
+			...anthropicModel ? [createCacheBreakpointMiddleware()] : [],
 			...memoryMiddlewareArray,
 			...interruptOn ? [(0, langchain.humanInTheLoopMiddleware)({ interruptOn })] : [],
 			...customMiddleware