deepagents 1.1.1 → 1.3.0

package/dist/index.d.ts

@@ -4,10 +4,11 @@ import { AnnotationRoot } from "@langchain/langgraph";
 import { StructuredTool as StructuredTool$1 } from "@langchain/core/tools";
 import { BaseLanguageModel, LanguageModelLike } from "@langchain/core/language_models/base";
 import { BaseCheckpointSaver, BaseStore } from "@langchain/langgraph-checkpoint";
+import { Runnable } from "@langchain/core/runnables";
 import { InteropZodObject } from "@langchain/core/utils/types";
 
 //#region src/backends/protocol.d.ts
-
+type MaybePromise<T> = T | Promise<T>;
 /**
  * Structured file listing info.
  *
@@ -65,6 +66,8 @@ interface WriteResult {
    * External backends set null (already persisted to disk/S3/database/etc).
    */
   filesUpdate?: Record<string, FileData> | null;
+  /** Metadata for the write operation, attached to the ToolMessage */
+  metadata?: Record<string, unknown>;
 }
 /**
  * Result from backend edit operations.
@@ -85,6 +88,8 @@ interface EditResult {
   filesUpdate?: Record<string, FileData> | null;
   /** Number of replacements made, undefined on failure */
   occurrences?: number;
+  /** Metadata for the edit operation, attached to the ToolMessage */
+  metadata?: Record<string, unknown>;
 }
 /**
  * Protocol for pluggable memory backends (single, unified).
@@ -107,7 +112,7 @@ interface BackendProtocol {
    * @param path - Absolute path to directory
    * @returns List of FileInfo objects for files and directories directly in the directory
    */
-  lsInfo(path: string): FileInfo[] | Promise<FileInfo[]>;
+  lsInfo(path: string): MaybePromise<FileInfo[]>;
   /**
    * Read file content with line numbers or an error string.
    *
@@ -116,7 +121,14 @@ interface BackendProtocol {
    * @param limit - Maximum number of lines to read, default 2000
    * @returns Formatted file content with line numbers, or error message
    */
-  read(filePath: string, offset?: number, limit?: number): string | Promise<string>;
+  read(filePath: string, offset?: number, limit?: number): MaybePromise<string>;
+  /**
+   * Read file content as raw FileData.
+   *
+   * @param filePath - Absolute file path
+   * @returns Raw file content as FileData
+   */
+  readRaw(filePath: string): MaybePromise<FileData>;
   /**
    * Structured search results or error string for invalid input.
    *
@@ -127,7 +139,7 @@ interface BackendProtocol {
    * @param glob - Optional glob pattern to filter files (e.g., "*.py")
    * @returns List of GrepMatch objects or error string for invalid regex
    */
-  grepRaw(pattern: string, path?: string | null, glob?: string | null): GrepMatch[] | string | Promise<GrepMatch[] | string>;
+  grepRaw(pattern: string, path?: string | null, glob?: string | null): MaybePromise<GrepMatch[] | string>;
   /**
    * Structured glob matching returning FileInfo objects.
    *
@@ -135,7 +147,7 @@ interface BackendProtocol {
    * @param path - Base path to search from (default: "/")
    * @returns List of FileInfo objects matching the pattern
    */
-  globInfo(pattern: string, path?: string): FileInfo[] | Promise<FileInfo[]>;
+  globInfo(pattern: string, path?: string): MaybePromise<FileInfo[]>;
   /**
    * Create a new file.
    *
@@ -143,7 +155,7 @@ interface BackendProtocol {
    * @param content - File content as string
    * @returns WriteResult with error populated on failure
    */
-  write(filePath: string, content: string): WriteResult | Promise<WriteResult>;
+  write(filePath: string, content: string): MaybePromise<WriteResult>;
   /**
    * Edit a file by replacing string occurrences.
    *
@@ -153,7 +165,7 @@ interface BackendProtocol {
    * @param replaceAll - If true, replace all occurrences (default: false)
    * @returns EditResult with error, path, filesUpdate, and occurrences
    */
-  edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): EditResult | Promise<EditResult>;
+  edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): MaybePromise<EditResult>;
 }
 /**
  * State and store container for backend initialization.
@@ -210,6 +222,17 @@ interface FilesystemMiddlewareOptions {
 declare function createFilesystemMiddleware(options?: FilesystemMiddlewareOptions): langchain0.AgentMiddleware<any, undefined, any>;
 //#endregion
 //#region src/middleware/subagents.d.ts
+/**
+ * Type definitions for pre-compiled agents.
+ */
+interface CompiledSubAgent {
+  /** The name of the agent */
+  name: string;
+  /** The description of the agent */
+  description: string;
+  /** The agent instance */
+  runnable: ReactAgent<any, any, any, any> | Runnable;
+}
 /**
  * Type definitions for subagents
  */
@@ -242,7 +265,7 @@ interface SubAgentMiddlewareOptions {
   /** The tool configs for the default general-purpose subagent */
   defaultInterruptOn?: Record<string, boolean | InterruptOnConfig> | null;
   /** A list of additional subagents to provide to the agent */
-  subagents?: Array<SubAgent>;
+  subagents?: (SubAgent | CompiledSubAgent)[];
   /** Full system prompt override */
   systemPrompt?: string | null;
   /** Whether to include the general-purpose agent */
@@ -314,6 +337,13 @@ declare class StateBackend implements BackendProtocol {
    * @returns Formatted file content with line numbers, or error message
    */
   read(filePath: string, offset?: number, limit?: number): string;
+  /**
+   * Read file content as raw FileData.
+   *
+   * @param filePath - Absolute file path
+   * @returns Raw file content as FileData
+   */
+  readRaw(filePath: string): FileData;
   /**
    * Create a new file with content.
    * Returns WriteResult with filesUpdate to update LangGraph state.
@@ -360,7 +390,7 @@ declare class StoreBackend implements BackendProtocol {
    * [assistant_id, "filesystem"] to provide per-assistant isolation.
    * Otherwise return ["filesystem"].
    */
-  private getNamespace;
+  protected getNamespace(): string[];
   /**
    * Convert a store Item to FileData format.
    *
@@ -402,6 +432,13 @@ declare class StoreBackend implements BackendProtocol {
    * @returns Formatted file content with line numbers, or error message
    */
   read(filePath: string, offset?: number, limit?: number): Promise<string>;
+  /**
+   * Read file content as raw FileData.
+   *
+   * @param filePath - Absolute file path
+   * @returns Raw file content as FileData
+   */
+  readRaw(filePath: string): Promise<FileData>;
   /**
    * Create a new file with content.
    * Returns WriteResult. External storage sets filesUpdate=null.
@@ -469,6 +506,13 @@ declare class FilesystemBackend implements BackendProtocol {
    * @returns Formatted file content with line numbers, or error message
    */
   read(filePath: string, offset?: number, limit?: number): Promise<string>;
+  /**
+   * Read file content as raw FileData.
+   *
+   * @param filePath - Absolute file path
+   * @returns Raw file content as FileData
+   */
+  readRaw(filePath: string): Promise<FileData>;
   /**
    * Create a new file with content.
    * Returns WriteResult. External storage sets filesUpdate=null.
@@ -538,6 +582,13 @@ declare class CompositeBackend implements BackendProtocol {
    * @returns Formatted file content with line numbers, or error message
    */
   read(filePath: string, offset?: number, limit?: number): Promise<string>;
+  /**
+   * Read file content as raw FileData.
+   *
+   * @param filePath - Absolute file path
+   * @returns Raw file content as FileData
+   */
+  readRaw(filePath: string): Promise<FileData>;
   /**
    * Structured search results or error string for invalid input.
    */
@@ -581,7 +632,7 @@ interface CreateDeepAgentParams<ContextSchema extends AnnotationRoot<any> | Inte
   /** Custom middleware to apply after standard middleware */
   middleware?: AgentMiddleware[];
   /** List of subagent specifications for task delegation */
-  subagents?: SubAgent[];
+  subagents?: (SubAgent | CompiledSubAgent)[];
   /** Structured output response format for the agent */
   responseFormat?: any;
   /** Optional schema for context (not persisted between invocations) */
@@ -621,4 +672,4 @@ interface CreateDeepAgentParams<ContextSchema extends AnnotationRoot<any> | Inte
  */
 declare function createDeepAgent<ContextSchema extends AnnotationRoot<any> | InteropZodObject = AnnotationRoot<any>>(params?: CreateDeepAgentParams<ContextSchema>): ReactAgent<any, any, ContextSchema, any>;
 //#endregion
-export { type BackendFactory, type BackendProtocol, CompositeBackend, type CreateDeepAgentParams, type EditResult, type FileData, type FileInfo, FilesystemBackend, type FilesystemMiddlewareOptions, type GrepMatch, StateBackend, StoreBackend, type SubAgent, type SubAgentMiddlewareOptions, type WriteResult, createDeepAgent, createFilesystemMiddleware, createPatchToolCallsMiddleware, createSubAgentMiddleware };
+export { type BackendFactory, type BackendProtocol, type CompiledSubAgent, CompositeBackend, type CreateDeepAgentParams, type EditResult, type FileData, type FileInfo, FilesystemBackend, type FilesystemMiddlewareOptions, type GrepMatch, StateBackend, StoreBackend, type SubAgent, type SubAgentMiddlewareOptions, type WriteResult, createDeepAgent, createFilesystemMiddleware, createPatchToolCallsMiddleware, createSubAgentMiddleware };

package/dist/index.js

@@ -312,6 +312,17 @@ var StateBackend = class {
 		return formatReadResponse(fileData, offset, limit);
 	}
 	/**
+	* Read file content as raw FileData.
+	*
+	* @param filePath - Absolute file path
+	* @returns Raw file content as FileData
+	*/
+	readRaw(filePath) {
+		const fileData = this.getFiles()[filePath];
+		if (!fileData) throw new Error(`File '${filePath}' not found`);
+		return fileData;
+	}
+	/**
 	* Create a new file with content.
 	* Returns WriteResult with filesUpdate to update LangGraph state.
 	*/
@@ -403,12 +414,6 @@ function getBackend(backend, stateAndStore) {
 	if (typeof backend === "function") return backend(stateAndStore);
 	return backend;
 }
-/**
-* Helper to await if Promise, otherwise return value directly.
-*/
-async function awaitIfPromise(value) {
-	return value;
-}
 const FILESYSTEM_SYSTEM_PROMPT = `You have access to a virtual filesystem. All file paths must start with a /.
 
 - ls: list files in a directory (requires absolute path)
@@ -426,14 +431,15 @@ const GREP_TOOL_DESCRIPTION = "Search for a regex pattern in files. Returns matc
 /**
 * Create ls tool using backend.
 */
-function createLsTool(backend, customDescription) {
+function createLsTool(backend, options) {
+	const { customDescription } = options;
 	return tool(async (input, config) => {
 		const resolvedBackend = getBackend(backend, {
 			state: getCurrentTaskInput(config),
 			store: config.store
 		});
 		const path$1 = input.path || "/";
-		const infos = await awaitIfPromise(resolvedBackend.lsInfo(path$1));
+		const infos = await resolvedBackend.lsInfo(path$1);
 		if (infos.length === 0) return `No files found in ${path$1}`;
 		const lines = [];
 		for (const info of infos) if (info.is_dir) lines.push(`${info.path} (directory)`);
@@ -451,14 +457,15 @@ function createLsTool(backend, customDescription) {
 /**
 * Create read_file tool using backend.
 */
-function createReadFileTool(backend, customDescription) {
+function createReadFileTool(backend, options) {
+	const { customDescription } = options;
 	return tool(async (input, config) => {
 		const resolvedBackend = getBackend(backend, {
 			state: getCurrentTaskInput(config),
 			store: config.store
 		});
 		const { file_path, offset = 0, limit = 2e3 } = input;
-		return await awaitIfPromise(resolvedBackend.read(file_path, offset, limit));
+		return await resolvedBackend.read(file_path, offset, limit);
 	}, {
 		name: "read_file",
 		description: customDescription || READ_FILE_TOOL_DESCRIPTION,
@@ -472,24 +479,27 @@ function createReadFileTool(backend, customDescription) {
 /**
 * Create write_file tool using backend.
 */
-function createWriteFileTool(backend, customDescription) {
+function createWriteFileTool(backend, options) {
+	const { customDescription } = options;
 	return tool(async (input, config) => {
 		const resolvedBackend = getBackend(backend, {
 			state: getCurrentTaskInput(config),
 			store: config.store
 		});
 		const { file_path, content } = input;
-		const result = await awaitIfPromise(resolvedBackend.write(file_path, content));
+		const result = await resolvedBackend.write(file_path, content);
 		if (result.error) return result.error;
+		const message = new ToolMessage({
+			content: `Successfully wrote to '${file_path}'`,
+			tool_call_id: config.toolCall?.id,
+			name: "write_file",
+			metadata: result.metadata
+		});
 		if (result.filesUpdate) return new Command({ update: {
 			files: result.filesUpdate,
-			messages: [new ToolMessage({
-				content: `Successfully wrote to '${file_path}'`,
-				tool_call_id: config.toolCall?.id,
-				name: "write_file"
-			})]
+			messages: [message]
 		} });
-		return `Successfully wrote to '${file_path}'`;
+		return message;
 	}, {
 		name: "write_file",
 		description: customDescription || WRITE_FILE_TOOL_DESCRIPTION,
@@ -502,23 +512,25 @@ function createWriteFileTool(backend, customDescription) {
 /**
 * Create edit_file tool using backend.
 */
-function createEditFileTool(backend, customDescription) {
+function createEditFileTool(backend, options) {
+	const { customDescription } = options;
 	return tool(async (input, config) => {
 		const resolvedBackend = getBackend(backend, {
 			state: getCurrentTaskInput(config),
 			store: config.store
 		});
 		const { file_path, old_string, new_string, replace_all = false } = input;
-		const result = await awaitIfPromise(resolvedBackend.edit(file_path, old_string, new_string, replace_all));
+		const result = await resolvedBackend.edit(file_path, old_string, new_string, replace_all);
 		if (result.error) return result.error;
-		const message = `Successfully replaced ${result.occurrences} occurrence(s) in '${file_path}'`;
+		const message = new ToolMessage({
+			content: `Successfully replaced ${result.occurrences} occurrence(s) in '${file_path}'`,
+			tool_call_id: config.toolCall?.id,
+			name: "edit_file",
+			metadata: result.metadata
+		});
 		if (result.filesUpdate) return new Command({ update: {
 			files: result.filesUpdate,
-			messages: [new ToolMessage({
-				content: message,
-				tool_call_id: config.toolCall?.id,
-				name: "edit_file"
-			})]
+			messages: [message]
 		} });
 		return message;
 	}, {
@@ -535,14 +547,15 @@ function createEditFileTool(backend, customDescription) {
 /**
 * Create glob tool using backend.
 */
-function createGlobTool(backend, customDescription) {
+function createGlobTool(backend, options) {
+	const { customDescription } = options;
 	return tool(async (input, config) => {
 		const resolvedBackend = getBackend(backend, {
 			state: getCurrentTaskInput(config),
 			store: config.store
 		});
 		const { pattern, path: path$1 = "/" } = input;
-		const infos = await awaitIfPromise(resolvedBackend.globInfo(pattern, path$1));
+		const infos = await resolvedBackend.globInfo(pattern, path$1);
 		if (infos.length === 0) return `No files found matching pattern '${pattern}'`;
 		return infos.map((info) => info.path).join("\n");
 	}, {
@@ -557,14 +570,15 @@ function createGlobTool(backend, customDescription) {
 /**
 * Create grep tool using backend.
 */
-function createGrepTool(backend, customDescription) {
+function createGrepTool(backend, options) {
+	const { customDescription } = options;
 	return tool(async (input, config) => {
 		const resolvedBackend = getBackend(backend, {
 			state: getCurrentTaskInput(config),
 			store: config.store
 		});
 		const { pattern, path: path$1 = "/", glob = null } = input;
-		const result = await awaitIfPromise(resolvedBackend.grepRaw(pattern, path$1, glob));
+		const result = await resolvedBackend.grepRaw(pattern, path$1, glob);
 		if (typeof result === "string") return result;
 		if (result.length === 0) return `No matches found for pattern '${pattern}'`;
 		const lines = [];
@@ -594,12 +608,12 @@ function createFilesystemMiddleware(options = {}) {
 	const { backend = (stateAndStore) => new StateBackend(stateAndStore), systemPrompt: customSystemPrompt = null, customToolDescriptions = null, toolTokenLimitBeforeEvict = 2e4 } = options;
 	const systemPrompt = customSystemPrompt || FILESYSTEM_SYSTEM_PROMPT;
 	const tools = [
-		createLsTool(backend, customToolDescriptions?.ls ?? null),
-		createReadFileTool(backend, customToolDescriptions?.read_file ?? null),
-		createWriteFileTool(backend, customToolDescriptions?.write_file ?? null),
-		createEditFileTool(backend, customToolDescriptions?.edit_file ?? null),
-		createGlobTool(backend, customToolDescriptions?.glob ?? null),
-		createGrepTool(backend, customToolDescriptions?.grep ?? null)
+		createLsTool(backend, { customDescription: customToolDescriptions?.ls }),
+		createReadFileTool(backend, { customDescription: customToolDescriptions?.read_file }),
+		createWriteFileTool(backend, { customDescription: customToolDescriptions?.write_file }),
+		createEditFileTool(backend, { customDescription: customToolDescriptions?.edit_file }),
+		createGlobTool(backend, { customDescription: customToolDescriptions?.glob }),
+		createGrepTool(backend, { customDescription: customToolDescriptions?.grep })
 	];
 	return createMiddleware({
 		name: "FilesystemMiddleware",
@@ -625,7 +639,7 @@ function createFilesystemMiddleware(options = {}) {
 						store: request.config?.store
 					});
 					const evictPath = `/large_tool_results/${sanitizeToolCallId(request.toolCall?.id || msg.tool_call_id)}`;
-					const writeResult = await awaitIfPromise(resolvedBackend.write(evictPath, msg.content));
+					const writeResult = await resolvedBackend.write(evictPath, msg.content);
 					if (writeResult.error) return {
 						message: msg,
 						filesUpdate: null
@@ -871,15 +885,18 @@ function getSubagents(options) {
 	}
 	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
-		});
+		if ("runnable" in agentParams) agents[agentParams.name] = agentParams.runnable;
+		else {
+			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
+			});
+		}
 	}
 	return {
 		agents,
@@ -1146,17 +1163,26 @@ var StoreBackend = class {
 	* @returns Formatted file content with line numbers, or error message
 	*/
 	async read(filePath, offset = 0, limit = 2e3) {
-		const store = this.getStore();
-		const namespace = this.getNamespace();
-		const item = await store.get(namespace, filePath);
-		if (!item) return `Error: File '${filePath}' not found`;
 		try {
-			return formatReadResponse(this.convertStoreItemToFileData(item), offset, limit);
+			return formatReadResponse(await this.readRaw(filePath), offset, limit);
 		} catch (e) {
 			return `Error: ${e.message}`;
 		}
 	}
 	/**
+	* Read file content as raw FileData.
+	*
+	* @param filePath - Absolute file path
+	* @returns Raw file content as FileData
+	*/
+	async readRaw(filePath) {
+		const store = this.getStore();
+		const namespace = this.getNamespace();
+		const item = await store.get(namespace, filePath);
+		if (!item) throw new Error(`File '${filePath}' not found`);
+		return this.convertStoreItemToFileData(item);
+	}
+	/**
 	* Create a new file with content.
 	* Returns WriteResult. External storage sets filesUpdate=null.
 	*/
@@ -1389,6 +1415,37 @@ var FilesystemBackend = class {
 		}
 	}
 	/**
+	* Read file content as raw FileData.
+	*
+	* @param filePath - Absolute file path
+	* @returns Raw file content as FileData
+	*/
+	async readRaw(filePath) {
+		const resolvedPath = this.resolvePath(filePath);
+		let content;
+		let stat;
+		if (SUPPORTS_NOFOLLOW) {
+			stat = await fs.stat(resolvedPath);
+			if (!stat.isFile()) throw new Error(`File '${filePath}' not found`);
+			const fd = await fs.open(resolvedPath, fsSync.constants.O_RDONLY | fsSync.constants.O_NOFOLLOW);
+			try {
+				content = await fd.readFile({ encoding: "utf-8" });
+			} finally {
+				await fd.close();
+			}
+		} else {
+			stat = await fs.lstat(resolvedPath);
+			if (stat.isSymbolicLink()) throw new Error(`Symlinks are not allowed: ${filePath}`);
+			if (!stat.isFile()) throw new Error(`File '${filePath}' not found`);
+			content = await fs.readFile(resolvedPath, "utf-8");
+		}
+		return {
+			content: content.split("\n"),
+			created_at: stat.ctime.toISOString(),
+			modified_at: stat.mtime.toISOString()
+		};
+	}
+	/**
 	* Create a new file with content.
 	* Returns WriteResult. External storage sets filesUpdate=null.
 	*/
@@ -1720,6 +1777,16 @@ var CompositeBackend = class {
 		return await backend.read(strippedKey, offset, limit);
 	}
 	/**
+	* Read file content as raw FileData.
+	*
+	* @param filePath - Absolute file path
+	* @returns Raw file content as FileData
+	*/
+	async readRaw(filePath) {
+		const [backend, strippedKey] = this.getBackendAndKey(filePath);
+		return await backend.readRaw(strippedKey);
+	}
+	/**
 	* Structured search results or error string for invalid input.
 	*/
 	async grepRaw(pattern, path$1 = "/", glob = null) {
@@ -1829,8 +1896,8 @@ function createDeepAgent(params = {}) {
 				createFilesystemMiddleware({ backend: filesystemBackend }),
 				summarizationMiddleware({
 					model,
-					maxTokensBeforeSummary: 17e4,
-					messagesToKeep: 6
+					trigger: { tokens: 17e4 },
+					keep: { messages: 6 }
 				}),
 				anthropicPromptCachingMiddleware({ unsupportedModelBehavior: "ignore" }),
 				createPatchToolCallsMiddleware()
@@ -1841,8 +1908,8 @@ function createDeepAgent(params = {}) {
 		}),
 		summarizationMiddleware({
 			model,
-			maxTokensBeforeSummary: 17e4,
-			messagesToKeep: 6
+			trigger: { tokens: 17e4 },
+			keep: { messages: 6 }
 		}),
 		anthropicPromptCachingMiddleware({ unsupportedModelBehavior: "ignore" }),
 		createPatchToolCallsMiddleware()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepagents",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Deep Agents - a library for building controllable AI agents with LangGraph",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,9 +36,9 @@
     "@changesets/cli": "^2.29.7",
     "@eslint/eslintrc": "^3.1.0",
     "@eslint/js": "^9.19.0",
-    "@langchain/langgraph-checkpoint": "^0.0.13",
+    "@langchain/langgraph-checkpoint": "^1.0.0",
     "@langchain/openai": "^1.0.0",
-    "@langchain/tavily": "^0.1.4",
+    "@langchain/tavily": "^1.0.0",
     "@tsconfig/recommended": "^1.0.10",
     "@types/micromatch": "^4.0.10",
     "@types/node": "^22.13.5",