deepagents 1.8.1 → 1.8.3

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,
@@ -1462,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",
@@ -1799,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.
 	*/
@@ -1824,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
@@ -2835,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;
 	}
@@ -3828,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.
 	*
@@ -4757,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:
@@ -4793,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
@@ -4820,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.
@@ -4869,7 +4976,10 @@ function createDeepAgent(params = {}) {
 			model,
 			backend: filesystemBackend
 		}),
-		(0, langchain.anthropicPromptCachingMiddleware)({ unsupportedModelBehavior: "ignore" }),
+		(0, langchain.anthropicPromptCachingMiddleware)({
+			unsupportedModelBehavior: "ignore",
+			minMessagesToCache: 1
+		}),
 		createPatchToolCallsMiddleware()
 	];
 	/**
@@ -4892,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
@@ -4902,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
@@ -4915,7 +5033,10 @@ function createDeepAgent(params = {}) {
 		checkpointer,
 		store,
 		name
-	}).withConfig({ recursionLimit: 1e4 });
+	}).withConfig({
+		recursionLimit: 1e4,
+		metadata: { ls_integration: "deepagents" }
+	});
 }
 
 //#endregion