deepagents 1.2.0 → 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,14 +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): FileData | Promise<FileData>;
+  readRaw(filePath: string): MaybePromise<FileData>;
   /**
    * Structured search results or error string for invalid input.
    *
@@ -134,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.
    *
@@ -142,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.
    *
@@ -150,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.
    *
@@ -160,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.
@@ -198,15 +203,6 @@ interface StateAndStore {
 type BackendFactory = (stateAndStore: StateAndStore) => BackendProtocol;
 //#endregion
 //#region src/middleware/fs.d.ts
-type FilesystemEventResponse = {
-  kind: "raw-contents";
-} | {
-  kind: "metadata";
-  data: Record<string, unknown>;
-};
-interface FilesystemEvents {
-  onWrite?: (path: string, backend: BackendProtocol) => void | FilesystemEventResponse | Promise<void | FilesystemEventResponse>;
-}
 /**
  * Options for creating filesystem middleware.
  */
@@ -219,8 +215,6 @@ interface FilesystemMiddlewareOptions {
   customToolDescriptions?: Record<string, string> | null;
   /** Optional token limit before evicting a tool result to the filesystem (default: 20000 tokens, ~80KB) */
   toolTokenLimitBeforeEvict?: number | null;
-  /** Filesystem events callbacks */
-  events?: FilesystemEvents;
 }
 /**
  * Create filesystem middleware with all tools and features.
@@ -228,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
  */
@@ -260,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 */
@@ -627,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) */
@@ -667,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

@@ -414,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)
@@ -445,7 +439,7 @@ function createLsTool(backend, options) {
 			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)`);
@@ -471,7 +465,7 @@ function createReadFileTool(backend, options) {
 			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,
@@ -486,7 +480,7 @@ function createReadFileTool(backend, options) {
 * Create write_file tool using backend.
 */
 function createWriteFileTool(backend, options) {
-	const { customDescription, events } = options;
+	const { customDescription } = options;
 	return tool(async (input, config) => {
 		const resolvedBackend = getBackend(backend, {
 			state: getCurrentTaskInput(config),
@@ -495,16 +489,11 @@ function createWriteFileTool(backend, options) {
 		const { file_path, content } = input;
 		const result = await resolvedBackend.write(file_path, content);
 		if (result.error) return result.error;
-		const resolved = await events?.onWrite?.(file_path, resolvedBackend) ?? void 0;
-		const metadata = await (async () => {
-			if (resolved?.kind === "metadata") return resolved.data;
-			if (resolved?.kind === "raw-contents") return { ...await resolvedBackend.readRaw(file_path) };
-		})();
 		const message = new ToolMessage({
 			content: `Successfully wrote to '${file_path}'`,
 			tool_call_id: config.toolCall?.id,
 			name: "write_file",
-			metadata
+			metadata: result.metadata
 		});
 		if (result.filesUpdate) return new Command({ update: {
 			files: result.filesUpdate,
@@ -524,25 +513,20 @@ function createWriteFileTool(backend, options) {
 * Create edit_file tool using backend.
 */
 function createEditFileTool(backend, options) {
-	const { customDescription, events } = 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 resolved = await events?.onWrite?.(file_path, resolvedBackend) ?? void 0;
-		const metadata = await (async () => {
-			if (resolved?.kind === "metadata") return resolved.data;
-			if (resolved?.kind === "raw-contents") return { ...await resolvedBackend.readRaw(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
+			metadata: result.metadata
 		});
 		if (result.filesUpdate) return new Command({ update: {
 			files: result.filesUpdate,
@@ -571,7 +555,7 @@ function createGlobTool(backend, options) {
 			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");
 	}, {
@@ -594,7 +578,7 @@ function createGrepTool(backend, options) {
 			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 = [];
@@ -621,33 +605,15 @@ function createGrepTool(backend, options) {
 * Create filesystem middleware with all tools and features.
 */
 function createFilesystemMiddleware(options = {}) {
-	const { backend = (stateAndStore) => new StateBackend(stateAndStore), systemPrompt: customSystemPrompt = null, customToolDescriptions = null, toolTokenLimitBeforeEvict = 2e4, events = void 0 } = 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, {
-			customDescription: customToolDescriptions?.ls ?? null,
-			events
-		}),
-		createReadFileTool(backend, {
-			customDescription: customToolDescriptions?.read_file ?? null,
-			events
-		}),
-		createWriteFileTool(backend, {
-			customDescription: customToolDescriptions?.write_file ?? null,
-			events
-		}),
-		createEditFileTool(backend, {
-			customDescription: customToolDescriptions?.edit_file ?? null,
-			events
-		}),
-		createGlobTool(backend, {
-			customDescription: customToolDescriptions?.glob ?? null,
-			events
-		}),
-		createGrepTool(backend, {
-			customDescription: customToolDescriptions?.grep ?? null,
-			events
-		})
+		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",
@@ -673,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
@@ -919,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepagents",
-  "version": "1.2.0",
+  "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",