deepagents 1.8.4 → 1.8.5

package/dist/index.cjs

@@ -1,4 +1,4 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -7,16 +7,12 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") {
-		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-			key = keys[i];
-			if (!__hasOwnProp.call(to, key) && key !== except) {
-				__defProp(to, key, {
-					get: ((k) => from[k]).bind(null, key),
-					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-				});
-			}
-		}
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
 	}
 	return to;
 };
@@ -24,7 +20,6 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	value: mod,
 	enumerable: true
 }) : target, mod));
-
 //#endregion
 let langchain = require("langchain");
 let _langchain_core_runnables = require("@langchain/core/runnables");
@@ -37,7 +32,6 @@ let _langchain_core_messages = require("@langchain/core/messages");
 let zod = require("zod");
 let yaml = require("yaml");
 yaml = __toESM(yaml);
-let uuid = require("uuid");
 let _langchain_core_errors = require("@langchain/core/errors");
 let langchain_chat_models_universal = require("langchain/chat_models/universal");
 let node_fs_promises = require("node:fs/promises");
@@ -50,9 +44,9 @@ let node_child_process = require("node:child_process");
 node_child_process = __toESM(node_child_process);
 let fast_glob = require("fast-glob");
 fast_glob = __toESM(fast_glob);
+let langsmith_experimental_sandbox = require("langsmith/experimental/sandbox");
 let node_os = require("node:os");
 node_os = __toESM(node_os);
-
 //#region src/backends/protocol.ts
 /**
 * Type guard to check if a backend supports execution.
@@ -61,7 +55,7 @@ node_os = __toESM(node_os);
 * @returns True if the backend implements SandboxBackendProtocol
 */
 function isSandboxBackend(backend) {
-	return typeof backend.execute === "function" && typeof backend.id === "string";
+	return typeof backend.execute === "function" && typeof backend.id === "string" && backend.id !== "";
 }
 const SANDBOX_ERROR_SYMBOL = Symbol.for("sandbox.error");
 /**
@@ -112,7 +106,6 @@ var SandboxError = class SandboxError extends Error {
 		return typeof error === "object" && error !== null && error[SANDBOX_ERROR_SYMBOL] === true;
 	}
 };
-
 //#endregion
 //#region src/backends/utils.ts
 /**
@@ -124,7 +117,6 @@ 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]";
 /**
@@ -154,17 +146,17 @@ function formatContentWithLineNumbers(content, startLine = 1) {
 	for (let i = 0; i < lines.length; i++) {
 		const line = lines[i];
 		const lineNum = i + startLine;
-		if (line.length <= MAX_LINE_LENGTH) resultLines.push(`${lineNum.toString().padStart(LINE_NUMBER_WIDTH)}\t${line}`);
+		if (line.length <= 1e4) resultLines.push(`${lineNum.toString().padStart(6)}\t${line}`);
 		else {
 			const numChunks = Math.ceil(line.length / MAX_LINE_LENGTH);
 			for (let chunkIdx = 0; chunkIdx < numChunks; chunkIdx++) {
 				const start = chunkIdx * MAX_LINE_LENGTH;
 				const end = Math.min(start + MAX_LINE_LENGTH, line.length);
 				const chunk = line.substring(start, end);
-				if (chunkIdx === 0) resultLines.push(`${lineNum.toString().padStart(LINE_NUMBER_WIDTH)}\t${chunk}`);
+				if (chunkIdx === 0) resultLines.push(`${lineNum.toString().padStart(6)}\t${chunk}`);
 				else {
 					const continuationMarker = `${lineNum}.${chunkIdx}`;
-					resultLines.push(`${continuationMarker.padStart(LINE_NUMBER_WIDTH)}\t${chunk}`);
+					resultLines.push(`${continuationMarker.padStart(6)}\t${chunk}`);
 				}
 			}
 		}
@@ -267,13 +259,13 @@ function performStringReplacement(content, oldString, newString, replaceAll) {
 function truncateIfTooLong(result) {
 	if (Array.isArray(result)) {
 		const totalChars = result.reduce((sum, item) => sum + item.length, 0);
-		if (totalChars > TOOL_RESULT_TOKEN_LIMIT * 4) {
+		if (totalChars > 2e4 * 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]";
+	if (result.length > 2e4 * 4) return result.substring(0, TOOL_RESULT_TOKEN_LIMIT * 4) + "\n... [results truncated, try being more specific with your parameters]";
 	return result;
 }
 /**
@@ -381,7 +373,6 @@ function grepMatchesFromFiles(files, pattern, path$9 = null, glob = null) {
 	}
 	return matches;
 }
-
 //#endregion
 //#region src/backends/state.ts
 /**
@@ -581,7 +572,6 @@ var StateBackend = class {
 		return responses;
 	}
 };
-
 //#endregion
 //#region src/middleware/fs.ts
 /**
@@ -614,6 +604,20 @@ var StateBackend = class {
 *    These tools return minimal confirmation messages and are never expected to produce
 *    output large enough to exceed token limits, so checking them would be unnecessary.
 */
+/**
+* All tool names registered by FilesystemMiddleware.
+* This is the single source of truth — used by createDeepAgent to detect
+* collisions with user-supplied tools at construction time.
+*/
+const FILESYSTEM_TOOL_NAMES = [
+	"ls",
+	"read_file",
+	"write_file",
+	"edit_file",
+	"glob",
+	"grep",
+	"execute"
+];
 const TOOLS_EXCLUDED_FROM_EVICTION = [
 	"ls",
 	"glob",
@@ -623,17 +627,6 @@ const TOOLS_EXCLUDED_FROM_EVICTION = [
 	"write_file"
 ];
 /**
-* Approximate number of characters per token for truncation calculations.
-* Using 4 chars per token as a conservative approximation (actual ratio varies by content)
-* This errs on the high side to avoid premature eviction of content that might fit.
-*/
-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.
 */
@@ -875,13 +868,13 @@ function createReadFileTool(backend, options) {
 			state: (0, _langchain_langgraph.getCurrentTaskInput)(config),
 			store: config.store
 		});
-		const { file_path, offset = DEFAULT_READ_LINE_OFFSET, limit = DEFAULT_READ_LINE_LIMIT } = input;
+		const { file_path, offset = 0, limit = 100 } = 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) {
+		if (toolTokenLimitBeforeEvict && result.length >= 4 * toolTokenLimitBeforeEvict) {
 			const truncationMsg = READ_FILE_TRUNCATION_MSG.replace("{file_path}", file_path);
-			const maxContentLength = NUM_CHARS_PER_TOKEN * toolTokenLimitBeforeEvict - truncationMsg.length;
+			const maxContentLength = 4 * toolTokenLimitBeforeEvict - truncationMsg.length;
 			result = result.substring(0, maxContentLength) + truncationMsg;
 		}
 		return result;
@@ -890,8 +883,8 @@ function createReadFileTool(backend, options) {
 		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(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")
+			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(100).describe("Maximum number of lines to read")
 		})
 	});
 }
@@ -1055,21 +1048,22 @@ function createExecuteTool(backend, options) {
 function createFilesystemMiddleware(options = {}) {
 	const { backend = (stateAndStore) => new StateBackend(stateAndStore), systemPrompt: customSystemPrompt = null, customToolDescriptions = null, toolTokenLimitBeforeEvict = 2e4 } = options;
 	const baseSystemPrompt = customSystemPrompt || FILESYSTEM_SYSTEM_PROMPT;
+	const allToolsByName = {
+		ls: createLsTool(backend, { customDescription: customToolDescriptions?.ls }),
+		read_file: createReadFileTool(backend, {
+			customDescription: customToolDescriptions?.read_file,
+			toolTokenLimitBeforeEvict
+		}),
+		write_file: createWriteFileTool(backend, { customDescription: customToolDescriptions?.write_file }),
+		edit_file: createEditFileTool(backend, { customDescription: customToolDescriptions?.edit_file }),
+		glob: createGlobTool(backend, { customDescription: customToolDescriptions?.glob }),
+		grep: createGrepTool(backend, { customDescription: customToolDescriptions?.grep }),
+		execute: createExecuteTool(backend, { customDescription: customToolDescriptions?.execute })
+	};
 	return (0, langchain.createMiddleware)({
 		name: "FilesystemMiddleware",
 		stateSchema: FilesystemStateSchema,
-		tools: [
-			createLsTool(backend, { customDescription: customToolDescriptions?.ls }),
-			createReadFileTool(backend, {
-				customDescription: customToolDescriptions?.read_file,
-				toolTokenLimitBeforeEvict
-			}),
-			createWriteFileTool(backend, { customDescription: customToolDescriptions?.write_file }),
-			createEditFileTool(backend, { customDescription: customToolDescriptions?.edit_file }),
-			createGlobTool(backend, { customDescription: customToolDescriptions?.glob }),
-			createGrepTool(backend, { customDescription: customToolDescriptions?.grep }),
-			createExecuteTool(backend, { customDescription: customToolDescriptions?.execute })
-		],
+		tools: Object.values(allToolsByName),
 		wrapModelCall: async (request, handler) => {
 			const supportsExecution = isSandboxBackend(getBackend(backend, {
 				state: request.state || {},
@@ -1092,7 +1086,7 @@ function createFilesystemMiddleware(options = {}) {
 			if (toolName && TOOLS_EXCLUDED_FROM_EVICTION.includes(toolName)) return handler(request);
 			const result = await handler(request);
 			async function processToolMessage(msg, toolTokenLimitBeforeEvict) {
-				if (typeof msg.content === "string" && msg.content.length > toolTokenLimitBeforeEvict * NUM_CHARS_PER_TOKEN) {
+				if (typeof msg.content === "string" && msg.content.length > toolTokenLimitBeforeEvict * 4) {
 					const resolvedBackend = getBackend(backend, {
 						state: request.state || {},
 						store: request.runtime?.store
@@ -1156,7 +1150,6 @@ function createFilesystemMiddleware(options = {}) {
 		}
 	});
 }
-
 //#endregion
 //#region src/middleware/subagents.ts
 /**
@@ -1537,12 +1530,23 @@ 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.
+* Patch tool call / tool response parity in a messages array.
+*
+* Ensures strict 1:1 correspondence between AIMessage tool_calls and
+* ToolMessage responses:
+*
+* 1. **Dangling tool_calls** — an AIMessage contains a tool_call with no
+*    matching ToolMessage anywhere after it. A synthetic cancellation
+*    ToolMessage is inserted immediately after the AIMessage.
+*
+* 2. **Orphaned ToolMessages** — a ToolMessage whose `tool_call_id` does not
+*    match any tool_call in a preceding AIMessage. The ToolMessage is removed.
+*
+* Both directions are required for providers that enforce strict parity
+* (e.g. Google Gemini returns 400 INVALID_ARGUMENT otherwise).
 *
 * @param messages - The messages array to patch
 * @returns Object with patched messages and needsPatch flag
@@ -1552,13 +1556,23 @@ function patchDanglingToolCalls(messages) {
 		patchedMessages: [],
 		needsPatch: false
 	};
+	const allToolCallIds = /* @__PURE__ */ new Set();
+	for (const msg of messages) if (langchain.AIMessage.isInstance(msg) && msg.tool_calls != null) {
+		for (const tc of msg.tool_calls) if (tc.id) allToolCallIds.add(tc.id);
+	}
 	const patchedMessages = [];
 	let needsPatch = false;
 	for (let i = 0; i < messages.length; i++) {
 		const msg = messages[i];
+		if (langchain.ToolMessage.isInstance(msg)) {
+			if (!allToolCallIds.has(msg.tool_call_id)) {
+				needsPatch = true;
+				continue;
+			}
+		}
 		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)) {
+			for (const toolCall of msg.tool_calls) if (!messages.slice(i + 1).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({
@@ -1575,11 +1589,18 @@ function patchDanglingToolCalls(messages) {
 	};
 }
 /**
-* Create middleware that patches dangling tool calls in the messages history.
+* Create middleware that enforces strict tool call / tool response parity in
+* the messages history.
+*
+* Two kinds of violations are repaired:
+* 1. **Dangling tool_calls** — an AIMessage contains tool_calls with no
+*    matching ToolMessage responses. Synthetic cancellation ToolMessages are
+*    injected so every tool_call has a response.
+* 2. **Orphaned ToolMessages** — a ToolMessage exists whose `tool_call_id`
+*    does not match any tool_call in a preceding AIMessage. These are removed.
 *
-* 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 is critical for providers like Google Gemini that reject requests with
+* mismatched function call / function response counts (400 INVALID_ARGUMENT).
 *
 * This middleware patches in two places:
 * 1. `beforeAgent`: Patches state at the start of the agent loop (handles most cases)
@@ -1587,7 +1608,7 @@ function patchDanglingToolCalls(messages) {
 *    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
+* @returns AgentMiddleware that enforces tool call / response parity
 *
 * @example
 * ```typescript
@@ -1625,7 +1646,6 @@ function createPatchToolCallsMiddleware() {
 		}
 	});
 }
-
 //#endregion
 //#region src/values.ts
 /**
@@ -1660,7 +1680,6 @@ const filesValue = new _langchain_langgraph.ReducedValue(zod.z.record(zod.z.stri
 	inputSchema: zod.z.record(zod.z.string(), FileDataSchema.nullable()).optional(),
 	reducer: fileDataReducer
 });
-
 //#endregion
 //#region src/middleware/memory.ts
 /**
@@ -1879,7 +1898,6 @@ function createMemoryMiddleware(options) {
 		}
 	});
 }
-
 //#endregion
 //#region src/middleware/skills.ts
 /**
@@ -1925,7 +1943,6 @@ function createMemoryMiddleware(options) {
 const MAX_SKILL_FILE_SIZE = 10 * 1024 * 1024;
 const MAX_SKILL_NAME_LENGTH = 64;
 const MAX_SKILL_DESCRIPTION_LENGTH = 1024;
-const MAX_SKILL_COMPATIBILITY_LENGTH = 500;
 /**
 * Zod schema for a single skill metadata entry.
 */
@@ -2035,7 +2052,7 @@ function validateSkillName$1(name, directoryName) {
 		valid: false,
 		error: "name is required"
 	};
-	if (name.length > MAX_SKILL_NAME_LENGTH) return {
+	if (name.length > 64) return {
 		valid: false,
 		error: "name exceeds 64 characters"
 	};
@@ -2109,7 +2126,7 @@ function formatSkillAnnotations(skill) {
 *   validation errors occur
 */
 function parseSkillMetadataFromContent(content, skillPath, directoryName) {
-	if (content.length > MAX_SKILL_FILE_SIZE) {
+	if (content.length > 10485760) {
 		console.warn(`Skipping ${skillPath}: content too large (${content.length} bytes)`);
 		return null;
 	}
@@ -2139,7 +2156,7 @@ function parseSkillMetadataFromContent(content, skillPath, directoryName) {
 	const validation = validateSkillName$1(name, directoryName);
 	if (!validation.valid) console.warn(`Skill '${name}' in ${skillPath} does not follow Agent Skills specification: ${validation.error}. Consider renaming for spec compliance.`);
 	let descriptionStr = description;
-	if (descriptionStr.length > MAX_SKILL_DESCRIPTION_LENGTH) {
+	if (descriptionStr.length > 1024) {
 		console.warn(`Description exceeds ${MAX_SKILL_DESCRIPTION_LENGTH} characters in ${skillPath}, truncating`);
 		descriptionStr = descriptionStr.slice(0, MAX_SKILL_DESCRIPTION_LENGTH);
 	}
@@ -2149,9 +2166,9 @@ function parseSkillMetadataFromContent(content, skillPath, directoryName) {
 	else allowedTools = String(rawTools).split(/\s+/).filter(Boolean);
 	else allowedTools = [];
 	let compatibilityStr = String(frontmatterData.compatibility ?? "").trim() || null;
-	if (compatibilityStr && compatibilityStr.length > MAX_SKILL_COMPATIBILITY_LENGTH) {
-		console.warn(`Compatibility exceeds ${MAX_SKILL_COMPATIBILITY_LENGTH} characters in ${skillPath}, truncating`);
-		compatibilityStr = compatibilityStr.slice(0, MAX_SKILL_COMPATIBILITY_LENGTH);
+	if (compatibilityStr && compatibilityStr.length > 500) {
+		console.warn(`Compatibility exceeds 500 characters in ${skillPath}, truncating`);
+		compatibilityStr = compatibilityStr.slice(0, 500);
 	}
 	return {
 		name,
@@ -2294,7 +2311,6 @@ function createSkillsMiddleware(options) {
 		}
 	});
 }
-
 //#endregion
 //#region src/middleware/utils.ts
 /**
@@ -2302,7 +2318,6 @@ function createSkillsMiddleware(options) {
 *
 * This module provides shared helpers used across middleware implementations.
 */
-
 //#endregion
 //#region src/middleware/summarization.ts
 /**
@@ -2507,7 +2522,7 @@ function createSummarizationMiddleware(options) {
 	*/
 	function getSessionId(state) {
 		if (state._summarizationSessionId) return state._summarizationSessionId;
-		if (!sessionId) sessionId = `session_${(0, uuid.v4)().substring(0, 8)}`;
+		if (!sessionId) sessionId = `session_${crypto.randomUUID().substring(0, 8)}`;
 		return sessionId;
 	}
 	/**
@@ -2992,7 +3007,6 @@ ${summary}
 		}
 	});
 }
-
 //#endregion
 //#region src/backends/store.ts
 const NAMESPACE_COMPONENT_RE = /^[A-Za-z0-9\-_.@+:~]+$/;
@@ -3336,7 +3350,6 @@ var StoreBackend = class {
 		return responses;
 	}
 };
-
 //#endregion
 //#region src/backends/filesystem.ts
 /**
@@ -3855,7 +3868,6 @@ var FilesystemBackend = class {
 		return responses;
 	}
 };
-
 //#endregion
 //#region src/backends/composite.ts
 /**
@@ -4104,7 +4116,6 @@ var CompositeBackend = class {
 		return results;
 	}
 };
-
 //#endregion
 //#region src/backends/local-shell.ts
 /**
@@ -4409,7 +4420,6 @@ var LocalShellBackend = class LocalShellBackend extends FilesystemBackend {
 		return backend;
 	}
 };
-
 //#endregion
 //#region src/backends/sandbox.ts
 /**
@@ -4808,7 +4818,197 @@ var BaseSandbox = class {
 		};
 	}
 };
-
+//#endregion
+//#region src/backends/langsmith.ts
+/**
+* LangSmith Sandbox backend for deepagents.
+*
+* @example
+* ```typescript
+* import { LangSmithSandbox, createDeepAgent } from "deepagents";
+*
+* const sandbox = await LangSmithSandbox.create({ templateName: "deepagents-cli" });
+*
+* const agent = createDeepAgent({ model, backend: sandbox });
+*
+* try {
+*   await agent.invoke({ messages: [...] });
+* } finally {
+*   await sandbox.close();
+* }
+* ```
+*/
+/**
+* LangSmith Sandbox backend for deepagents.
+*
+* Extends `BaseSandbox` to provide command execution and file operations
+* via the LangSmith Sandbox API.
+*
+* Use the static `LangSmithSandbox.create()` factory for the simplest setup,
+* or construct directly with an existing `Sandbox` instance.
+*/
+var LangSmithSandbox = class LangSmithSandbox extends BaseSandbox {
+	#sandbox;
+	#defaultTimeout;
+	#isRunning = true;
+	constructor(options) {
+		super();
+		this.#sandbox = options.sandbox;
+		this.#defaultTimeout = options.defaultTimeout ?? 1800;
+	}
+	/** Whether the sandbox is currently active. */
+	get isRunning() {
+		return this.#isRunning;
+	}
+	/** Return the LangSmith sandbox name as the unique identifier. */
+	get id() {
+		return this.#sandbox.name;
+	}
+	/**
+	* Execute a shell command in the LangSmith sandbox.
+	*
+	* @param command - Shell command string to execute
+	* @param options.timeout - Override timeout in seconds; 0 disables timeout
+	*/
+	async execute(command, options) {
+		const effectiveTimeout = options?.timeout !== void 0 ? options.timeout : this.#defaultTimeout;
+		const result = await this.#sandbox.run(command, { timeout: effectiveTimeout });
+		const out = result.stdout ?? "";
+		return {
+			output: result.stderr ? out ? `${out}\n${result.stderr}` : result.stderr : out,
+			exitCode: result.exit_code,
+			truncated: false
+		};
+	}
+	/**
+	* Download files from the sandbox using LangSmith's native file read API.
+	* @param paths - List of file paths to download
+	* @returns List of FileDownloadResponse objects, one per input path
+	*/
+	async downloadFiles(paths) {
+		const responses = [];
+		for (const path of paths) try {
+			const content = await this.#sandbox.read(path);
+			responses.push({
+				path,
+				content,
+				error: null
+			});
+		} catch (err) {
+			if (err instanceof langsmith_experimental_sandbox.LangSmithResourceNotFoundError) responses.push({
+				path,
+				content: null,
+				error: "file_not_found"
+			});
+			else if (err instanceof langsmith_experimental_sandbox.LangSmithSandboxError) {
+				const error = String(err.message).toLowerCase().includes("is a directory") ? "is_directory" : "file_not_found";
+				responses.push({
+					path,
+					content: null,
+					error
+				});
+			} else responses.push({
+				path,
+				content: null,
+				error: "invalid_path"
+			});
+		}
+		return responses;
+	}
+	/**
+	* Upload files to the sandbox using LangSmith's native file write API.
+	* @param files - List of [path, content] tuples to upload
+	* @returns List of FileUploadResponse objects, one per input file
+	*/
+	async uploadFiles(files) {
+		const responses = [];
+		for (const [path, content] of files) try {
+			await this.#sandbox.write(path, content);
+			responses.push({
+				path,
+				error: null
+			});
+		} catch {
+			responses.push({
+				path,
+				error: "permission_denied"
+			});
+		}
+		return responses;
+	}
+	/**
+	* Delete this sandbox and mark it as no longer running.
+	*
+	* After calling this, `isRunning` will be `false` and the sandbox
+	* cannot be used again.
+	*/
+	async close() {
+		await this.#sandbox.delete();
+		this.#isRunning = false;
+	}
+	/**
+	* Create and return a new LangSmithSandbox in one step.
+	*
+	* This is the recommended way to create a sandbox — no need to import
+	* anything from `langsmith/experimental/sandbox` directly.
+	*
+	* @example
+	* ```typescript
+	* const sandbox = await LangSmithSandbox.create({ templateName: "deepagents" });
+	* try {
+	*   const agent = createDeepAgent({ model, backend: sandbox });
+	*   await agent.invoke({ messages: [...] });
+	* } finally {
+	*   await sandbox.close();
+	* }
+	* ```
+	*/
+	static async create(options = {}) {
+		const { templateName = "deepagents", apiKey = process.env.LANGSMITH_API_KEY, defaultTimeout } = options;
+		return new LangSmithSandbox({
+			sandbox: await new langsmith_experimental_sandbox.SandboxClient({ apiKey }).createSandbox(templateName),
+			defaultTimeout
+		});
+	}
+};
+//#endregion
+//#region src/errors.ts
+const CONFIGURATION_ERROR_SYMBOL = Symbol.for("deepagents.configuration_error");
+/**
+* Thrown when `createDeepAgent` receives invalid configuration.
+*
+* Follows the same pattern as {@link SandboxError}: a human-readable
+* `message`, a structured `code` for programmatic handling, and a
+* static `isInstance` guard that works across realms.
+*
+* @example
+* ```typescript
+* try {
+*   createDeepAgent({ tools: [myTool] });
+* } catch (error) {
+*   if (ConfigurationError.isInstance(error)) {
+*     switch (error.code) {
+*       case "TOOL_NAME_COLLISION":
+*         console.error("Rename your tool:", error.message);
+*         break;
+*     }
+*   }
+* }
+* ```
+*/
+var ConfigurationError = class ConfigurationError extends Error {
+	[CONFIGURATION_ERROR_SYMBOL] = true;
+	name = "ConfigurationError";
+	constructor(message, code, cause) {
+		super(message);
+		this.code = code;
+		this.cause = cause;
+		Object.setPrototypeOf(this, ConfigurationError.prototype);
+	}
+	static isInstance(error) {
+		return typeof error === "object" && error !== null && error[CONFIGURATION_ERROR_SYMBOL] === true;
+	}
+};
 //#endregion
 //#region src/middleware/cache.ts
 /**
@@ -4852,10 +5052,14 @@ function createCacheBreakpointMiddleware() {
 		}
 	});
 }
-
 //#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.`;
+const BUILTIN_TOOL_NAMES = new Set([
+	...FILESYSTEM_TOOL_NAMES,
+	"task",
+	"write_todos"
+]);
 /**
 * Detect whether a model is an Anthropic model.
 * Used to gate Anthropic-specific prompt caching optimizations (cache_control breakpoints).
@@ -4901,6 +5105,8 @@ function isAnthropicModel(model) {
 */
 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;
+	const collidingTools = tools.map((t) => t.name).filter((n) => typeof n === "string" && BUILTIN_TOOL_NAMES.has(n));
+	if (collidingTools.length > 0) throw new ConfigurationError(`Tool name(s) [${collidingTools.join(", ")}] conflict with built-in tools. Rename your custom tools to avoid this.`, "TOOL_NAME_COLLISION");
 	const anthropicModel = isAnthropicModel(model);
 	const finalSystemPrompt = new langchain.SystemMessage({ content: systemPrompt ? typeof systemPrompt === "string" ? [{
 		type: "text",
@@ -4982,10 +5188,6 @@ function createDeepAgent(params = {}) {
 			model,
 			backend: filesystemBackend
 		}),
-		(0, langchain.anthropicPromptCachingMiddleware)({
-			unsupportedModelBehavior: "ignore",
-			minMessagesToCache: 1
-		}),
 		createPatchToolCallsMiddleware()
 	];
 	/**
@@ -5008,11 +5210,17 @@ function createDeepAgent(params = {}) {
 				createSubAgentMiddleware({
 					defaultModel: model,
 					defaultTools: tools,
-					defaultMiddleware: [...subagentMiddleware, ...anthropicModel ? [createCacheBreakpointMiddleware()] : []],
+					defaultMiddleware: [...subagentMiddleware, ...anthropicModel ? [(0, langchain.anthropicPromptCachingMiddleware)({
+						unsupportedModelBehavior: "ignore",
+						minMessagesToCache: 1
+					}), createCacheBreakpointMiddleware()] : []],
 					generalPurposeMiddleware: [
 						...subagentMiddleware,
 						...skillsMiddlewareArray,
-						...anthropicModel ? [createCacheBreakpointMiddleware()] : []
+						...anthropicModel ? [(0, langchain.anthropicPromptCachingMiddleware)({
+							unsupportedModelBehavior: "ignore",
+							minMessagesToCache: 1
+						}), createCacheBreakpointMiddleware()] : []
 					],
 					defaultInterruptOn: interruptOn,
 					subagents: processedSubagents,
@@ -5022,17 +5230,16 @@ function createDeepAgent(params = {}) {
 					model,
 					backend: filesystemBackend
 				}),
-				(0, langchain.anthropicPromptCachingMiddleware)({
-					unsupportedModelBehavior: "ignore",
-					minMessagesToCache: 1
-				}),
 				createPatchToolCallsMiddleware()
 			],
 			...skillsMiddlewareArray,
-			...anthropicModel ? [createCacheBreakpointMiddleware()] : [],
+			...customMiddleware,
+			...anthropicModel ? [(0, langchain.anthropicPromptCachingMiddleware)({
+				unsupportedModelBehavior: "ignore",
+				minMessagesToCache: 1
+			}), createCacheBreakpointMiddleware()] : [],
 			...memoryMiddlewareArray,
-			...interruptOn ? [(0, langchain.humanInTheLoopMiddleware)({ interruptOn })] : [],
-			...customMiddleware
+			...interruptOn ? [(0, langchain.humanInTheLoopMiddleware)({ interruptOn })] : []
 		],
 		...responseFormat != null && { responseFormat },
 		contextSchema,
@@ -5044,7 +5251,6 @@ function createDeepAgent(params = {}) {
 		metadata: { ls_integration: "deepagents" }
 	});
 }
-
 //#endregion
 //#region src/config.ts
 /**
@@ -5138,7 +5344,6 @@ function createSettings(options = {}) {
 		}
 	};
 }
-
 //#endregion
 //#region src/middleware/agent-memory.ts
 /**
@@ -5365,38 +5570,6 @@ function createAgentMemoryMiddleware(options) {
 		}
 	});
 }
-
-//#endregion
-//#region src/skills/loader.ts
-/**
-* Skill loader for parsing and loading agent skills from SKILL.md files.
-*
-* This module implements Anthropic's agent skills pattern with YAML frontmatter parsing.
-* Each skill is a directory containing a SKILL.md file with:
-* - YAML frontmatter (name, description required)
-* - Markdown instructions for the agent
-* - Optional supporting files (scripts, configs, etc.)
-*
-* @example
-* ```markdown
-* ---
-* name: web-research
-* description: Structured approach to conducting thorough web research
-* ---
-*
-* # Web Research Skill
-*
-* ## When to Use
-* - User asks you to research a topic
-* ...
-* ```
-*
-* @see https://agentskills.io/specification
-*/
-/** Maximum size for SKILL.md files (10MB) */
-const MAX_SKILL_FILE_SIZE$1 = 10 * 1024 * 1024;
-/** Agent Skills spec constraints */
-const MAX_SKILL_NAME_LENGTH$1 = 64;
 const MAX_SKILL_DESCRIPTION_LENGTH$1 = 1024;
 /** Pattern for validating skill names per Agent Skills spec */
 const SKILL_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
@@ -5441,7 +5614,7 @@ function validateSkillName(name, directoryName) {
 		valid: false,
 		error: "name is required"
 	};
-	if (name.length > MAX_SKILL_NAME_LENGTH$1) return {
+	if (name.length > 64) return {
 		valid: false,
 		error: "name exceeds 64 characters"
 	};
@@ -5481,7 +5654,7 @@ function parseFrontmatter(content) {
 function parseSkillMetadata(skillMdPath, source) {
 	try {
 		const stats = node_fs.default.statSync(skillMdPath);
-		if (stats.size > MAX_SKILL_FILE_SIZE$1) {
+		if (stats.size > 10485760) {
 			console.warn(`Skipping ${skillMdPath}: file too large (${stats.size} bytes)`);
 			return null;
 		}
@@ -5500,7 +5673,7 @@ function parseSkillMetadata(skillMdPath, source) {
 		const validation = validateSkillName(String(name), directoryName);
 		if (!validation.valid) console.warn(`Skill '${name}' in ${skillMdPath} does not follow Agent Skills spec: ${validation.error}. Consider renaming to be spec-compliant.`);
 		let descriptionStr = String(description);
-		if (descriptionStr.length > MAX_SKILL_DESCRIPTION_LENGTH$1) {
+		if (descriptionStr.length > 1024) {
 			console.warn(`Description exceeds ${MAX_SKILL_DESCRIPTION_LENGTH$1} chars in ${skillMdPath}, truncating`);
 			descriptionStr = descriptionStr.slice(0, MAX_SKILL_DESCRIPTION_LENGTH$1);
 		}
@@ -5588,14 +5761,15 @@ function listSkills(options) {
 	}
 	return Array.from(allSkills.values());
 }
-
 //#endregion
 exports.BaseSandbox = BaseSandbox;
 exports.CompositeBackend = CompositeBackend;
+exports.ConfigurationError = ConfigurationError;
 exports.DEFAULT_GENERAL_PURPOSE_DESCRIPTION = DEFAULT_GENERAL_PURPOSE_DESCRIPTION;
 exports.DEFAULT_SUBAGENT_PROMPT = DEFAULT_SUBAGENT_PROMPT;
 exports.FilesystemBackend = FilesystemBackend;
 exports.GENERAL_PURPOSE_SUBAGENT = GENERAL_PURPOSE_SUBAGENT;
+exports.LangSmithSandbox = LangSmithSandbox;
 exports.LocalShellBackend = LocalShellBackend;
 exports.MAX_SKILL_DESCRIPTION_LENGTH = MAX_SKILL_DESCRIPTION_LENGTH;
 exports.MAX_SKILL_FILE_SIZE = MAX_SKILL_FILE_SIZE;
@@ -5619,4 +5793,5 @@ exports.findProjectRoot = findProjectRoot;
 exports.isSandboxBackend = isSandboxBackend;
 exports.listSkills = listSkills;
 exports.parseSkillMetadata = parseSkillMetadata;
+
 //# sourceMappingURL=index.cjs.map