deepagents 1.9.1 → 1.10.1

package/dist/index.js

@@ -1,5 +1,5 @@
 import { AIMessage, HumanMessage, SystemMessage, ToolMessage, anthropicPromptCachingMiddleware, context, countTokensApproximately, createAgent, createMiddleware, humanInTheLoopMiddleware, todoListMiddleware, tool } from "langchain";
-import { Command, REMOVE_ALL_MESSAGES, ReducedValue, StateSchema, getConfig, getCurrentTaskInput, getStore, isCommand } from "@langchain/langgraph";
+import { ChatModelStreamImpl, Command, REMOVE_ALL_MESSAGES, ReducedValue, StateSchema, StreamChannel, getConfig, getCurrentTaskInput, getStore, isCommand } from "@langchain/langgraph";
 import { z } from "zod/v4";
 import micromatch from "micromatch";
 import path, { basename } from "path";
@@ -2438,6 +2438,13 @@ function createPatchToolCallsMiddleware() {
 			if (!needsPatch) return;
 			return { messages: [new RemoveMessage({ id: REMOVE_ALL_MESSAGES }), ...patchedMessages] };
 		},
+		/**
+		* Also patch in wrapModelCall as a safety net.
+		* This handles edge cases where:
+		* - HITL rejects a tool call during graph resume
+		* - The state update from beforeAgent might not be applied in time
+		* - The model would otherwise receive dangling tool_call_ids
+		*/
 		wrapModelCall: async (request, handler) => {
 			const messages = request.messages;
 			if (!messages || messages.length === 0) return handler(request);
@@ -2539,6 +2546,10 @@ const filesValue = new ReducedValue(z$1.record(z$1.string(), FileDataSchema).def
 * State schema for memory middleware.
 */
 const MemoryStateSchema = new StateSchema({
+	/**
+	* Dict mapping source paths to their loaded content.
+	* Marked as private so it's not included in the final agent state.
+	*/
 	memoryContents: z$1.record(z$1.string(), z$1.string()).optional(),
 	files: filesValue
 });
@@ -3247,7 +3258,9 @@ const CALLBACK_THREAD_ID_KEY = "callbackThreadId";
 * and read by `CompletionCallbackMiddleware` when sending callback
 * notifications.
 */
-const CompletionCallbackStateSchema = z$2.object({ [CALLBACK_THREAD_ID_KEY]: z$2.string().optional() });
+const CompletionCallbackStateSchema = z$2.object({ 
+/** The callback thread ID. Used to address the notification. */
+[CALLBACK_THREAD_ID_KEY]: z$2.string().optional() });
 /**
 * Build headers for the callback LangGraph server.
 *
@@ -3365,12 +3378,25 @@ function createCompletionCallbackMiddleware(options) {
 	return createMiddleware({
 		name: "CompletionCallbackMiddleware",
 		stateSchema: CompletionCallbackStateSchema,
+		/**
+		* After-agent hook: fires when the subagent completes successfully.
+		*
+		* Extracts the last message as a summary and sends it to the callback
+		* thread.
+		*/
 		async afterAgent(state, runtime) {
 			const callbackThreadId = state[CALLBACK_THREAD_ID_KEY];
 			if (callbackThreadId == null) throw new Error(`Missing required state key '${CALLBACK_THREAD_ID_KEY}'`);
 			const taskId = getTaskId(runtime);
 			await sendNotification(callbackThreadId, formatNotification(`Completed. Result: ${extractLastMessage(state, typeof taskId === "string" ? taskId : void 0)}`, runtime));
 		},
+		/**
+		* Wrap model calls to catch errors and notify the callback thread.
+		*
+		* If a model call raises an exception, a generic error message is
+		* reported to the callback thread before re-raising. The actual error
+		* details are not leaked to the callback agent.
+		*/
 		async wrapModelCall(request, handler) {
 			try {
 				return await handler(request);
@@ -3504,15 +3530,22 @@ Summary:`;
 * list on subsequent calls.
 */
 const SummarizationEventSchema = z$1.object({
+	/**
+	* The index in the state messages list where summarization occurred.
+	* Messages before this index have been summarized. */
 	cutoffIndex: z$1.number(),
+	/** The HumanMessage containing the summary. */
 	summaryMessage: z$1.instanceof(HumanMessage),
+	/** Path where the conversation history was offloaded, or null if offload failed. */
 	filePath: z$1.string().nullable()
 });
 /**
 * State schema for summarization middleware.
 */
 const SummarizationStateSchema = z$1.object({
+	/** Session ID for history file naming */
 	_summarizationSessionId: z$1.string().optional(),
+	/** Most recent summarization event (private state, not visible to agent) */
 	_summarizationEvent: SummarizationEventSchema.optional()
 });
 /**
@@ -6392,7 +6425,7 @@ var BaseSandbox = class {
 * ```typescript
 * import { LangSmithSandbox, createDeepAgent } from "deepagents";
 *
-* const sandbox = await LangSmithSandbox.create({ templateName: "deepagents-cli" });
+* const sandbox = await LangSmithSandbox.create({ snapshotId: "your-snapshot-id" });
 *
 * const agent = createDeepAgent({ model, backend: sandbox });
 *
@@ -6516,6 +6549,41 @@ var LangSmithSandbox = class LangSmithSandbox extends BaseSandbox {
 		this.#isRunning = false;
 	}
 	/**
+	* Start a stopped sandbox and wait until it is ready.
+	*
+	* After calling this, `isRunning` will be `true` and the sandbox
+	* can be used for command execution and file operations again.
+	*
+	* @param options - Start options (timeout, signal).
+	*/
+	async start(options = {}) {
+		await this.#sandbox.start(options);
+		this.#isRunning = true;
+	}
+	/**
+	* Stop the sandbox without deleting it.
+	*
+	* Sandbox files are preserved and the sandbox can be restarted later
+	* with `start()`. After calling this, `isRunning` will be `false`.
+	*/
+	async stop() {
+		await this.#sandbox.stop();
+		this.#isRunning = false;
+	}
+	/**
+	* Capture a snapshot from this running sandbox.
+	*
+	* Snapshots can be used to create new sandboxes via
+	* `LangSmithSandbox.create({ snapshotId })`.
+	*
+	* @param name - Name for the snapshot.
+	* @param options - Capture options (checkpoint, timeout).
+	* @returns The created Snapshot in "ready" status.
+	*/
+	async captureSnapshot(name, options = {}) {
+		return this.#sandbox.captureSnapshot(name, options);
+	}
+	/**
 	* Create and return a new LangSmithSandbox in one step.
 	*
 	* This is the recommended way to create a sandbox — no need to import
@@ -6523,7 +6591,10 @@ var LangSmithSandbox = class LangSmithSandbox extends BaseSandbox {
 	*
 	* @example
 	* ```typescript
-	* const sandbox = await LangSmithSandbox.create({ templateName: "deepagents" });
+	* const sandbox = await LangSmithSandbox.create({
+	*   snapshotId: "abc-123",
+	* });
+	*
 	* try {
 	*   const agent = createDeepAgent({ model, backend: sandbox });
 	*   await agent.invoke({ messages: [...] });
@@ -6532,10 +6603,14 @@ var LangSmithSandbox = class LangSmithSandbox extends BaseSandbox {
 	* }
 	* ```
 	*/
-	static async create(options = {}) {
-		const { templateName = "deepagents", apiKey = process.env.LANGSMITH_API_KEY, defaultTimeout, ...createSandboxOptions } = options;
+	static async create(options) {
+		const { templateName, apiKey = process.env.LANGSMITH_API_KEY, defaultTimeout, snapshotId, ...createSandboxOptions } = options;
+		if (snapshotId && templateName) throw new Error("snapshotId and templateName are mutually exclusive. Pass only one creation source.");
+		if (!snapshotId && !templateName) throw new Error("Either snapshotId or templateName is required. snapshotId is recommended — template-based creation is deprecated.");
+		const sandboxOptions = { ...createSandboxOptions };
+		if (templateName) sandboxOptions.snapshotName = templateName;
 		return new LangSmithSandbox({
-			sandbox: await new SandboxClient({ apiKey }).createSandbox(templateName, createSandboxOptions),
+			sandbox: await new SandboxClient({ apiKey }).createSandbox(snapshotId, sandboxOptions),
 			defaultTimeout
 		});
 	}
@@ -6622,6 +6697,271 @@ function createCacheBreakpointMiddleware() {
 	});
 }
 //#endregion
+//#region src/stream.ts
+/**
+* Deep Agent streaming support (experimental).
+*
+* Provides:
+* - `DeepAgentRunStream` — type overlay that adds `.subagents` to the
+*   `AgentRunStream` shape
+* - `createSubagentTransformer` — a `__native` transformer whose
+*   projection (`subagents`) lands directly on the `GraphRunStream`
+*   instance via langgraph-core's native transformer support
+*
+* See protocol proposal §15 (In-Process Streaming Interface) and §16
+* (Native Stream Transformers).
+*/
+function hasPrefix(ns, prefix) {
+	if (prefix.length > ns.length) return false;
+	for (let i = 0; i < prefix.length; i += 1) if (ns[i] !== prefix[i]) return false;
+	return true;
+}
+/**
+* Native transformer that correlates `task` tool calls into
+* {@link SubagentRunStream} objects and routes child-namespace
+* `tools` and `messages` events into per-subagent channels.
+*
+* Marked `__native: true` — the `subagents` projection key lands
+* directly on the `GraphRunStream` instance as `run.subagents`.
+*/
+function createSubagentTransformer(path) {
+	return () => {
+		const subagentsLog = StreamChannel.local();
+		const pendingByCallId = /* @__PURE__ */ new Map();
+		const pendingByNamespaceSegment = /* @__PURE__ */ new Map();
+		const latestValuesByNamespaceSegment = /* @__PURE__ */ new Map();
+		const subagentsByName = /* @__PURE__ */ new Map();
+		/** Maps tools-node namespace segment to subagent name. */
+		const toolsNodeToName = /* @__PURE__ */ new Map();
+		const childToolCalls = /* @__PURE__ */ new Map();
+		/** Active ChatModelStreamImpl per subagent (keyed by subagent name). */
+		const activeMessages = /* @__PURE__ */ new Map();
+		function deletePendingSubagent(pending) {
+			pendingByCallId.delete(pending.callId);
+			for (const [segment, entry] of pendingByNamespaceSegment) if (entry === pending) {
+				pendingByNamespaceSegment.delete(segment);
+				latestValuesByNamespaceSegment.delete(segment);
+			}
+		}
+		function subagentSegment(ns) {
+			return ns.length === path.length + 1 ? ns[path.length] : void 0;
+		}
+		function getOrCreateSubagentLogs(name) {
+			let logs = subagentsByName.get(name);
+			if (!logs) {
+				logs = {
+					messagesLog: StreamChannel.local(),
+					toolCallsLog: StreamChannel.local(),
+					nestedSubagentsLog: StreamChannel.local()
+				};
+				subagentsByName.set(name, logs);
+			}
+			return logs;
+		}
+		return {
+			__native: true,
+			init: () => ({ subagents: subagentsLog }),
+			process(event) {
+				if (!hasPrefix(event.params.namespace, path)) return true;
+				const ns = event.params.namespace;
+				const depth = ns.length - path.length;
+				if (depth <= 1 && event.method === "tools") {
+					const data = event.params.data;
+					const toolCallId = data.tool_call_id;
+					const toolName = data.tool_name;
+					if (toolName === "task" && data.event === "tool-started") {
+						const rawInput = data.input;
+						const input = typeof rawInput === "string" ? JSON.parse(rawInput) : rawInput ?? {};
+						const subagentName = input.subagent_type ?? "unknown";
+						const taskDescription = input.description ?? "";
+						let resolveTaskInput;
+						let resolveOutput;
+						let rejectOutput;
+						const taskInput = new Promise((res) => {
+							resolveTaskInput = res;
+						});
+						const output = new Promise((res, rej) => {
+							resolveOutput = res;
+							rejectOutput = rej;
+						});
+						const pending = {
+							name: subagentName,
+							callId: toolCallId,
+							resolveTaskInput,
+							resolveOutput,
+							rejectOutput
+						};
+						if (toolCallId) pendingByCallId.set(toolCallId, pending);
+						resolveTaskInput(taskDescription);
+						if (depth === 1) {
+							toolsNodeToName.set(ns[path.length], subagentName);
+							pendingByNamespaceSegment.set(ns[path.length], pending);
+						}
+						if (toolCallId) {
+							const taskSegment = `tools:${toolCallId}`;
+							toolsNodeToName.set(taskSegment, subagentName);
+							pendingByNamespaceSegment.set(taskSegment, pending);
+						}
+						const logs = getOrCreateSubagentLogs(subagentName);
+						subagentsLog.push({
+							name: subagentName,
+							taskInput,
+							output,
+							messages: logs.messagesLog,
+							toolCalls: logs.toolCallsLog,
+							subagents: logs.nestedSubagentsLog
+						});
+					}
+					if (toolName === "task" && toolCallId) {
+						const pending = pendingByCallId.get(toolCallId);
+						if (pending) {
+							if (data.event === "tool-finished") {
+								pending.resolveOutput(data.output);
+								deletePendingSubagent(pending);
+							} else if (data.event === "tool-error") {
+								const message = data.message ?? "unknown error";
+								pending.rejectOutput(new Error(message));
+								deletePendingSubagent(pending);
+							}
+						}
+					}
+				}
+				const segment = subagentSegment(ns);
+				const pending = segment ? pendingByNamespaceSegment.get(segment) : void 0;
+				if (pending) {
+					if (event.method === "values") latestValuesByNamespaceSegment.set(segment, event.params.data);
+					else if (event.method === "lifecycle") {
+						const data = event.params.data;
+						if (data.event === "completed" || data.event === "interrupted") {
+							pending.resolveOutput(latestValuesByNamespaceSegment.get(segment));
+							deletePendingSubagent(pending);
+						} else if (data.event === "failed") {
+							pending.rejectOutput(/* @__PURE__ */ new Error(`Subagent ${pending.name} failed`));
+							deletePendingSubagent(pending);
+						}
+					}
+				}
+				if (depth >= 2) {
+					const parentSegment = ns[path.length];
+					const subagentName = toolsNodeToName.get(parentSegment);
+					const logs = subagentName ? subagentsByName.get(subagentName) : void 0;
+					if (logs && subagentName) {
+						if (event.method === "tools") {
+							const data = event.params.data;
+							const toolCallId = data.tool_call_id;
+							const toolName = data.tool_name;
+							if (data.event === "tool-started") {
+								let resolveOutput;
+								let rejectOutput;
+								let resolveStatus;
+								let resolveError;
+								const output = new Promise((res, rej) => {
+									resolveOutput = res;
+									rejectOutput = rej;
+								});
+								const status = new Promise((res) => {
+									resolveStatus = res;
+								});
+								const error = new Promise((res) => {
+									resolveError = res;
+								});
+								childToolCalls.set(toolCallId, {
+									resolveOutput,
+									rejectOutput,
+									resolveStatus,
+									resolveError
+								});
+								const rawInput = data.input;
+								const parsedInput = typeof rawInput === "string" ? JSON.parse(rawInput) : rawInput;
+								logs.toolCallsLog.push({
+									name: toolName ?? "unknown",
+									callId: toolCallId,
+									input: parsedInput,
+									output,
+									status,
+									error
+								});
+							}
+							const pending = toolCallId ? childToolCalls.get(toolCallId) : void 0;
+							if (pending) {
+								if (data.event === "tool-finished") {
+									pending.resolveOutput(data.output);
+									pending.resolveStatus("finished");
+									pending.resolveError(void 0);
+									childToolCalls.delete(toolCallId);
+								} else if (data.event === "tool-error") {
+									const message = data.message ?? "unknown error";
+									pending.rejectOutput(new Error(message));
+									pending.resolveStatus("error");
+									pending.resolveError(message);
+									childToolCalls.delete(toolCallId);
+								}
+							}
+						}
+						if (event.method === "messages") {
+							const data = event.params.data;
+							if (data.event === "message-start") {
+								const eventsLog = StreamChannel.local();
+								const stream = new ChatModelStreamImpl(eventsLog);
+								eventsLog.push(data);
+								activeMessages.set(subagentName, {
+									stream,
+									eventsLog
+								});
+								logs.messagesLog.push(stream);
+							} else if (data.event === "message-finish") {
+								const active = activeMessages.get(subagentName);
+								if (active) {
+									active.eventsLog.push(data);
+									active.eventsLog.close();
+									activeMessages.delete(subagentName);
+								}
+							} else activeMessages.get(subagentName)?.eventsLog.push(data);
+						}
+					}
+				}
+				return true;
+			},
+			finalize() {
+				for (const pending of pendingByCallId.values()) pending.resolveOutput(void 0);
+				pendingByCallId.clear();
+				for (const pending of childToolCalls.values()) {
+					pending.resolveOutput(void 0);
+					pending.resolveStatus("finished");
+					pending.resolveError(void 0);
+				}
+				childToolCalls.clear();
+				for (const active of activeMessages.values()) active.eventsLog.fail(/* @__PURE__ */ new Error("run finalized before message completed"));
+				activeMessages.clear();
+				subagentsLog.close();
+				for (const logs of subagentsByName.values()) {
+					logs.toolCallsLog.close();
+					logs.messagesLog.close();
+					logs.nestedSubagentsLog.close();
+				}
+			},
+			fail(err) {
+				for (const pending of pendingByCallId.values()) pending.rejectOutput(err);
+				pendingByCallId.clear();
+				for (const pending of childToolCalls.values()) {
+					pending.rejectOutput(err);
+					pending.resolveStatus("error");
+					pending.resolveError(err instanceof Error ? err.message : String(err));
+				}
+				childToolCalls.clear();
+				for (const active of activeMessages.values()) active.eventsLog.fail(err);
+				activeMessages.clear();
+				subagentsLog.fail(err);
+				for (const logs of subagentsByName.values()) {
+					logs.toolCallsLog.fail(err);
+					logs.messagesLog.fail(err);
+					logs.nestedSubagentsLog.fail(err);
+				}
+			}
+		};
+	};
+}
+//#endregion
 //#region src/agent.ts
 const BASE_AGENT_PROMPT = context`
   You are a Deep Agent, an AI assistant that helps users accomplish tasks using tools. You respond with text and tool calls. The user can see your responses and tool outputs in real time.
@@ -6707,7 +7047,7 @@ function isAnthropicModel(model) {
 * ```
 */
 function createDeepAgent(params = {}) {
-	const { model = "anthropic:claude-sonnet-4-6", tools = [], systemPrompt, middleware: customMiddleware = [], subagents = [], responseFormat, contextSchema, checkpointer, store, backend = (config) => new StateBackend(config), interruptOn, name, memory, skills, permissions = [] } = params;
+	const { model = "anthropic:claude-sonnet-4-6", tools = [], systemPrompt, middleware: customMiddleware = [], subagents = [], responseFormat, contextSchema, checkpointer, store, backend = (config) => new StateBackend(config), interruptOn, name, memory, skills, permissions = [], streamTransformers = [] } = 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);
@@ -6802,6 +7142,7 @@ function createDeepAgent(params = {}) {
 	* - Middleware: AllMiddleware (built-in + custom + subagent middleware for state inference)
 	* - Tools: TTools
 	* - Subagents: TSubagents (for type-safe streaming)
+	* - StreamTransformers: TStreamTransformers
 	*/
 	return createAgent({
 		model,
@@ -6824,7 +7165,8 @@ function createDeepAgent(params = {}) {
 		contextSchema,
 		checkpointer,
 		store,
-		name
+		name,
+		streamTransformers: [createSubagentTransformer([]), ...streamTransformers]
 	}).withConfig({
 		recursionLimit: 1e4,
 		metadata: {
@@ -6964,7 +7306,9 @@ function createSettings(options = {}) {
 * State schema for agent memory middleware.
 */
 const AgentMemoryStateSchema = z$1.object({
+	/** Personal preferences from ~/.deepagents/{agent}/ (applies everywhere) */
 	userMemory: z$1.string().optional(),
+	/** Project-specific context (loaded from project root) */
 	projectMemory: z$1.string().optional()
 });
 /**
@@ -7344,6 +7688,6 @@ function listSkills(options) {
 	return Array.from(allSkills.values());
 }
 //#endregion
-export { BaseSandbox, CompositeBackend, ConfigurationError, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, FilesystemBackend, GENERAL_PURPOSE_SUBAGENT, LangSmithSandbox, LocalShellBackend, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, SandboxError, StateBackend, StoreBackend, TASK_SYSTEM_PROMPT, adaptBackendProtocol, adaptSandboxProtocol, computeSummarizationDefaults, createAgentMemoryMiddleware, createAsyncSubAgentMiddleware, createCompletionCallbackMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isAsyncSubAgent, isSandboxBackend, isSandboxProtocol, listSkills, parseSkillMetadata, resolveBackend };
+export { BaseSandbox, CompositeBackend, ConfigurationError, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, FilesystemBackend, GENERAL_PURPOSE_SUBAGENT, LangSmithSandbox, LocalShellBackend, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, SandboxError, StateBackend, StoreBackend, TASK_SYSTEM_PROMPT, adaptBackendProtocol, adaptSandboxProtocol, computeSummarizationDefaults, createAgentMemoryMiddleware, createAsyncSubAgentMiddleware, createCompletionCallbackMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSubagentTransformer, createSummarizationMiddleware, filesValue, findProjectRoot, isAsyncSubAgent, isSandboxBackend, isSandboxProtocol, listSkills, parseSkillMetadata, resolveBackend };
 
 //# sourceMappingURL=index.js.map