deepagents 1.12.2 → 1.12.4

package/dist/{langsmith-D2d3Dwcc.cjs → langsmith-BJ2PdYqB.cjs}

@@ -15,7 +15,7 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));
@@ -326,13 +326,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 > 2e4 * 4) {
+		if (totalChars > 8e4) {
 			const truncateAt = Math.floor(result.length * TOOL_RESULT_TOKEN_LIMIT * 4 / totalChars);
 			return [...result.slice(0, truncateAt), TRUNCATION_GUIDANCE];
 		}
 		return result;
 	}
-	if (result.length > 2e4 * 4) return result.substring(0, TOOL_RESULT_TOKEN_LIMIT * 4) + "\n... [results truncated, try being more specific with your parameters]";
+	if (result.length > 8e4) return result.substring(0, TOOL_RESULT_TOKEN_LIMIT * 4) + "\n... [results truncated, try being more specific with your parameters]";
 	return result;
 }
 /**
@@ -425,6 +425,30 @@ function globSearchFiles(files, pattern, path = "/") {
 	return matches.map(([fp]) => fp).join("\n");
 }
 /**
+* Format grep search results based on output mode.
+*
+* @param results - Dictionary mapping file paths to list of [line_num, line_content] tuples
+* @param outputMode - Output format - "files_with_matches", "content", or "count"
+* @returns Formatted string output
+*/
+function formatGrepResults(results, outputMode) {
+	if (outputMode === "files_with_matches") return Object.keys(results).sort().join("\n");
+	if (outputMode === "count") {
+		const lines = [];
+		for (const filePath of Object.keys(results).sort()) {
+			const count = results[filePath].length;
+			lines.push(`${filePath}: ${count}`);
+		}
+		return lines.join("\n");
+	}
+	const lines = [];
+	for (const filePath of Object.keys(results).sort()) {
+		lines.push(`${filePath}:`);
+		for (const [lineNum, line] of results[filePath]) lines.push(`  ${lineNum}: ${line}`);
+	}
+	return lines.join("\n");
+}
+/**
 * Return structured grep matches from an in-memory files mapping.
 *
 * Performs literal text search (not regex). Binary files are skipped.
@@ -455,6 +479,24 @@ function grepMatchesFromFiles(files, pattern, path = null, glob = null) {
 	return matches;
 }
 /**
+* Group structured matches into the legacy dict form used by formatters.
+*/
+function buildGrepResultsDict(matches) {
+	const grouped = {};
+	for (const m of matches) {
+		if (!grouped[m.path]) grouped[m.path] = [];
+		grouped[m.path].push([m.line, m.text]);
+	}
+	return grouped;
+}
+/**
+* Format structured grep matches using existing formatting logic.
+*/
+function formatGrepMatches(matches, outputMode) {
+	if (matches.length === 0) return "No matches found";
+	return formatGrepResults(buildGrepResultsDict(matches), outputMode);
+}
+/**
 * Determine MIME type from a file path's extension.
 *
 * Defaults to "text/plain" for unknown extensions. Only the known non-text
@@ -1445,7 +1487,7 @@ const TOOLS_EXCLUDED_FROM_EVICTION = FILESYSTEM_TOOL_NAMES.filter((name) => name
 * Base64-encoded content is ~33% larger, so 10MB raw ≈ 13.3MB in context.
 * This keeps inline multimodal payloads within all major provider limits.
 */
-const MAX_BINARY_READ_SIZE_BYTES = 10 * 1024 * 1024;
+const MAX_BINARY_READ_SIZE_BYTES = 10485760;
 /**
 * Template for truncation message in read_file.
 * {file_path} will be filled in at runtime.
@@ -1534,8 +1576,9 @@ function buildEvictedHumanContent(message, replacementText) {
 */
 function buildTruncatedHumanMessage(message, filePath) {
 	const contentSample = createContentPreview(extractTextFromMessage(message));
+	const evictedContent = buildEvictedHumanContent(message, TOO_LARGE_HUMAN_MSG.replace("{file_path}", filePath).replace("{content_sample}", contentSample));
 	return new langchain.HumanMessage({
-		content: buildEvictedHumanContent(message, TOO_LARGE_HUMAN_MSG.replace("{file_path}", filePath).replace("{content_sample}", contentSample)),
+		content: evictedContent,
 		id: message.id,
 		additional_kwargs: { ...message.additional_kwargs },
 		response_metadata: { ...message.response_metadata }
@@ -1809,7 +1852,7 @@ function createReadFileTool(backend, options) {
 			const sizeBytes = Math.ceil(base64Data.length * 3 / 4);
 			if (sizeBytes > 10485760) return [{
 				type: "text",
-				text: `Error: file too large to read (${Math.round(sizeBytes / (1024 * 1024))}MB exceeds ${MAX_BINARY_READ_SIZE_BYTES / (1024 * 1024)}MB limit for binary files)`
+				text: `Error: file too large to read (${Math.round(sizeBytes / 1048576)}MB exceeds ${MAX_BINARY_READ_SIZE_BYTES / 1048576}MB limit for binary files)`
 			}];
 			if (mimeType.startsWith("image/")) return [{
 				type: "image",
@@ -1956,23 +1999,14 @@ function createGrepTool(backend, options) {
 		const permissionError = checkPermission(permissions, "read", input.path ?? "/");
 		if (permissionError !== void 0) return toolError(runtime, "grep", permissionError);
 		const resolvedBackend = await resolveBackend(backend, runtime);
-		const { pattern, path = "/", glob = null } = input;
+		const { pattern, path = "/", glob = null, output_mode = "content" } = input;
 		const maxCount = input.max_count ?? grepMaxCount;
 		const result = await resolvedBackend.grep(pattern, path, glob, maxCount);
 		if (result.error) return result.error;
 		const matches = filterByPermissions(result.matches ?? [], permissions, "read", (m) => m.path);
 		if (matches.length === 0) return `No matches found for pattern '${pattern}'`;
-		const lines = [];
-		let currentFile = null;
-		for (const match of matches) {
-			if (match.path !== currentFile) {
-				currentFile = match.path;
-				lines.push(`\n${currentFile}:`);
-			}
-			lines.push(`  ${match.line}: ${match.text}`);
-		}
-		const truncated = truncateIfTooLong(lines);
-		let content = Array.isArray(truncated) ? truncated.join("\n") : truncated;
+		const truncated = truncateIfTooLong(formatGrepMatches(matches, output_mode));
+		let content = typeof truncated === "string" ? truncated : truncated.join("\n");
 		if (result.truncated) content += `\n\n${GREP_TRUNCATION_NOTE}`;
 		return content;
 	}, {
@@ -1982,7 +2016,12 @@ function createGrepTool(backend, options) {
 			pattern: zod_v4.z.string().describe("Literal text pattern to search for (not regex)"),
 			path: zod_v4.z.string().optional().default("/").describe("Base path to search from (default: /)"),
 			glob: zod_v4.z.string().optional().nullable().default(null).describe("Optional glob pattern to filter files (e.g., '*.py')"),
-			max_count: zod_v4.z.number().int().positive().optional().nullable().default(null).describe("Optional cap on the total number of matches returned across all files. Leave unset to use the configured default. When the cap is hit, results are truncated and a note says so; narrow the pattern or path to see the rest.")
+			max_count: zod_v4.z.coerce.number().int().positive().optional().nullable().default(null).describe("Optional cap on the total number of matches returned across all files. Leave unset to use the configured default. When the cap is hit, results are truncated and a note says so; narrow the pattern or path to see the rest."),
+			output_mode: zod_v4.z.enum([
+				"files_with_matches",
+				"content",
+				"count"
+			]).optional().default("content").describe("Output format: 'files_with_matches' lists matching file paths, 'content' shows matching lines (default), 'count' shows match counts per file")
 		})
 	});
 }
@@ -2119,9 +2158,10 @@ function createFilesystemMiddleware(options = {}) {
 		const evictPath = `/large_tool_results/${sanitizeToolCallId(fallbackToolCallId || msg.tool_call_id)}.txt`;
 		const writeResult = await resolvedBackend.write(evictPath, textContent);
 		const contentSample = createContentPreview(textContent);
+		const replacementText = writeResult.error ? `Tool result too large, but the result could not be saved to the filesystem: ${writeResult.error}` : TOO_LARGE_TOOL_MSG.replace("{tool_call_id}", msg.tool_call_id).replace("{file_path}", evictPath).replace("{content_sample}", contentSample);
 		return {
 			message: new langchain.ToolMessage({
-				content: writeResult.error ? `Tool result too large, but the result could not be saved to the filesystem: ${writeResult.error}` : TOO_LARGE_TOOL_MSG.replace("{tool_call_id}", msg.tool_call_id).replace("{file_path}", evictPath).replace("{content_sample}", contentSample),
+				content: replacementText,
 				tool_call_id: msg.tool_call_id,
 				name: msg.name,
 				id: msg.id,
@@ -2238,23 +2278,18 @@ const SUBAGENT_RESPONSE_FORMAT_CONFIG_KEY = "__deepagents_subagent_response_form
 */
 const DEFAULT_SUBAGENT_PROMPT = "In order to complete the objective that the user asks of you, you have access to a number of standard tools.";
 /**
-* State keys that are excluded when passing state to subagents and when returning
-* updates from subagents.
-*
-* When returning updates:
-* 1. The messages key is handled explicitly to ensure only the final message is included
-* 2. The todos and structuredResponse keys are excluded as they do not have a defined reducer
-*    and no clear meaning for returning them from a subagent to the main agent.
-* 3. The skillsMetadata and memoryContents keys are automatically excluded from subagent output
-*    to prevent parent state from leaking to child agents. Each agent loads its own skills/memory
-*    independently based on its middleware configuration.
+* State keys excluded when passing state to subagents and when returning
+* updates from subagents. Summarization keys are excluded because their
+* cutoffIndex is only valid against the message list it was computed from.
 */
 const EXCLUDED_STATE_KEYS = [
 	"messages",
 	"todos",
 	"structuredResponse",
 	"skillsMetadata",
-	"memoryContents"
+	"memoryContents",
+	"_summarizationEvent",
+	"_summarizationSessionId"
 ];
 /**
 * Default description for the general-purpose subagent.
@@ -2466,6 +2501,7 @@ function createTaskTool(options) {
 		}
 		return subagentGraphs[subagentType];
 	}
+	const finalTaskDescription = taskDescription ? taskDescription : getTaskToolDescription(subagentDescriptions);
 	return (0, langchain.tool)(async (input, config) => {
 		const { description, subagent_type } = input;
 		if (!(subagent_type in subagentGraphs)) {
@@ -2475,6 +2511,7 @@ function createTaskTool(options) {
 		const subagent = selectSubagent(subagent_type, config);
 		const subagentState = filterStateForSubagent((0, _langchain_langgraph.getCurrentTaskInput)());
 		subagentState.messages = [new _langchain_core_messages.HumanMessage({ content: description })];
+		subagentState._summarizationSessionId = `session_${crypto.randomUUID().substring(0, 8)}`;
 		const subagentConfig = {
 			...config,
 			metadata: {
@@ -2501,7 +2538,7 @@ function createTaskTool(options) {
 		return returnCommandWithStateUpdate(result, config.toolCall.id);
 	}, {
 		name: "task",
-		description: taskDescription ? taskDescription : getTaskToolDescription(subagentDescriptions),
+		description: finalTaskDescription,
 		schema: zod_v4.z.object({
 			description: zod_v4.z.string().describe("The task to execute with the selected agent"),
 			subagent_type: zod_v4.z.string().describe(`Name of the agent to use. Available: ${Object.keys(subagentGraphs).join(", ")}`)
@@ -2513,18 +2550,19 @@ function createTaskTool(options) {
 */
 function createSubAgentMiddleware(options) {
 	const { defaultModel, defaultTools = [], defaultMiddleware = null, generalPurposeMiddleware = null, defaultInterruptOn = null, subagents = [], systemPrompt = null, generalPurposeAgent = true, taskDescription = null } = options;
+	const taskTool = createTaskTool({
+		defaultModel,
+		defaultTools,
+		defaultMiddleware,
+		generalPurposeMiddleware,
+		defaultInterruptOn,
+		subagents,
+		generalPurposeAgent,
+		taskDescription
+	});
 	return (0, langchain.createMiddleware)({
 		name: "subAgentMiddleware",
-		tools: [createTaskTool({
-			defaultModel,
-			defaultTools,
-			defaultMiddleware,
-			generalPurposeMiddleware,
-			defaultInterruptOn,
-			subagents,
-			generalPurposeAgent,
-			taskDescription
-		})],
+		tools: [taskTool],
 		wrapModelCall: async (request, handler) => {
 			if (systemPrompt !== null) return handler({
 				...request,
@@ -2714,6 +2752,43 @@ function isAnthropicModel(model) {
 	return model.getName() === "ChatAnthropic";
 }
 /**
+* A one-shot promise whose settlement is controlled externally.
+*
+* Use this when one part of a workflow must wait for an event that is owned
+* elsewhere—for example, a queued mutation waiting for the worker that will
+* push it. `Deferred` is awaitable because it implements `PromiseLike`, and
+* `.promise` is available when a concrete `Promise` is required.
+*
+* The first call to `resolve` or `reject` wins; later calls are ignored. This
+* class deliberately does not provide cancellation, reset, or notification
+* semantics. It models exactly one eventual outcome.
+*/
+var Deferred = class {
+	promise;
+	settled = false;
+	resolvePromise;
+	rejectPromise;
+	constructor() {
+		this.promise = new Promise((resolve, reject) => {
+			this.resolvePromise = resolve;
+			this.rejectPromise = reject;
+		});
+	}
+	resolve(value) {
+		if (this.settled) return;
+		this.settled = true;
+		this.resolvePromise(value);
+	}
+	reject(reason) {
+		if (this.settled) return;
+		this.settled = true;
+		this.rejectPromise(reason);
+	}
+	then(onfulfilled, onrejected) {
+		return this.promise.then(onfulfilled, onrejected);
+	}
+};
+/**
 * Detect whether a model is an AWS Bedrock Converse model.
 *
 * Accepts the wider `RunnableInterface` shape (the type of `request.model`
@@ -3029,7 +3104,7 @@ function createMemoryMiddleware(options) {
 * });
 * ```
 */
-const MAX_SKILL_FILE_SIZE = 10 * 1024 * 1024;
+const MAX_SKILL_FILE_SIZE = 10485760;
 const DEFAULT_SKILL_READ_LINE_LIMIT = 1e3;
 const MAX_SKILL_NAME_LENGTH = 64;
 const MAX_SKILL_DESCRIPTION_LENGTH = 1024;
@@ -3797,7 +3872,6 @@ function createCompletionCallbackMiddleware(options) {
 * from `langchain` directly.
 */
 const DEFAULT_MESSAGES_TO_KEEP = 20;
-const DEFAULT_TRIM_TOKEN_LIMIT = 4e3;
 const FALLBACK_TRIGGER = {
 	type: "tokens",
 	value: 17e4
@@ -3914,7 +3988,7 @@ function isSummaryMessage(msg) {
 * @returns AgentMiddleware for summarization and history offloading
 */
 function createSummarizationMiddleware(options) {
-	const { model, backend, summaryPrompt = DEFAULT_SUMMARY_PROMPT, trimTokensToSummarize = DEFAULT_TRIM_TOKEN_LIMIT, historyPathPrefix = "/conversation_history" } = options;
+	const { model, backend, summaryPrompt = DEFAULT_SUMMARY_PROMPT, trimTokensToSummarize, historyPathPrefix = "/conversation_history" } = options;
 	let trigger = options.trigger;
 	let keep = options.keep ?? {
 		type: "messages",
@@ -4118,7 +4192,9 @@ function createSummarizationMiddleware(options) {
 	* This gives a more accurate picture of what actually gets sent to the model.
 	*/
 	function countTotalTokens(messages, systemMessage, tools) {
-		return (0, langchain.countTokensApproximately)(systemMessage && langchain.SystemMessage.isInstance(systemMessage) ? [systemMessage, ...messages] : [...messages], tools && Array.isArray(tools) && tools.length > 0 ? tools : null);
+		const countedMessages = systemMessage && langchain.SystemMessage.isInstance(systemMessage) ? [systemMessage, ...messages] : [...messages];
+		const toolsArray = tools && Array.isArray(tools) && tools.length > 0 ? tools : null;
+		return (0, langchain.countTokensApproximately)(countedMessages, toolsArray);
 	}
 	/**
 	* Truncate ToolMessage content so that the total payload fits within the
@@ -4265,7 +4341,8 @@ function createSummarizationMiddleware(options) {
 	*/
 	async function createSummary(messages, chatModel) {
 		let messagesToSummarize = messages;
-		if ((0, langchain.countTokensApproximately)(messages) > trimTokensToSummarize) {
+		const tokens = (0, langchain.countTokensApproximately)(messages);
+		if (trimTokensToSummarize !== void 0 && tokens > trimTokensToSummarize) {
 			let kept = 0;
 			const trimmedMessages = [];
 			for (let i = messages.length - 1; i >= 0; i--) {
@@ -4278,8 +4355,7 @@ function createSummarizationMiddleware(options) {
 		}
 		const conversation = (0, _langchain_core_messages.getBufferString)(messagesToSummarize);
 		const prompt = summaryPrompt.replace("{conversation}", conversation);
-		const response = await chatModel.invoke([new langchain.HumanMessage({ content: prompt })]);
-		return typeof response.content === "string" ? response.content : JSON.stringify(response.content);
+		return (await chatModel.invoke([new langchain.HumanMessage({ content: prompt })])).text;
 	}
 	/**
 	* Build the summary message with file path reference.
@@ -6572,9 +6648,36 @@ var StoreBackend = class {
 /**
 * ContextHubBackend: Store files in a LangSmith Hub agent repo (persistent).
 */
-const URL_COMMIT_SUFFIX_RE = /:([0-9a-f]{8,64})$/i;
+const CONTEXT_URL_COMMIT_PATH_RE = /^\/context\/([^/]+)\/([0-9a-f]{8})$/;
+const LEGACY_URL_COMMIT_PATH_RE = /^\/hub\/([^/]+)\/([^/:]+):([0-9a-f]{8})$/;
+const MUTATION_COALESCE_MS = 50;
+const MAX_CONFLICT_RETRIES = 3;
 const TEXT_MIME_TYPE = "text/plain";
 const FNMATCH_OPTIONS = { bash: true };
+function parseHubTargetIdentifier(identifier) {
+	if (!identifier || identifier.split("/").length > 2 || identifier.startsWith("/") || identifier.endsWith("/") || identifier.split(":").length > 2) return null;
+	const [ownerNamePart] = identifier.split(":");
+	if (ownerNamePart.includes("/")) {
+		const [owner, name] = ownerNamePart.split("/", 2);
+		return owner && name ? [owner, name] : null;
+	}
+	return ownerNamePart ? ["-", ownerNamePart] : null;
+}
+function parseCommitHashFromUrl(url, identifier) {
+	try {
+		const pathname = decodeURIComponent(new URL(url).pathname);
+		const target = parseHubTargetIdentifier(identifier);
+		if (target === null) return null;
+		const [targetOwner, targetName] = target;
+		const contextMatch = CONTEXT_URL_COMMIT_PATH_RE.exec(pathname);
+		if (contextMatch !== null && contextMatch[1] === targetName) return contextMatch[2];
+		const legacyMatch = LEGACY_URL_COMMIT_PATH_RE.exec(pathname);
+		if (legacyMatch !== null && legacyMatch[1] === targetOwner && legacyMatch[2] === targetName) return legacyMatch[3];
+		return null;
+	} catch {
+		return null;
+	}
+}
 function getErrorMessage(error) {
 	if (typeof error === "string") return error;
 	if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") return error.message;
@@ -6613,6 +6716,12 @@ function getLangSmithStatus(error) {
 	const maybeError = error;
 	if (typeof maybeError.status === "number") return maybeError.status;
 }
+function createLangSmithConflictError(message) {
+	const error = new Error(message);
+	error.name = "LangSmithConflictError";
+	error.status = 409;
+	return error;
+}
 function mapHubFileOperationError(error) {
 	const status = getLangSmithStatus(error);
 	if (status === 401 || status === 403) return "permission_denied";
@@ -6622,12 +6731,49 @@ function mapHubFileOperationError(error) {
 /**
 * Backend that stores files in a LangSmith Hub agent repo (persistent).
 */
+/**
+* Backend that stores files in a LangSmith Hub agent repository.
+*
+* ## Mutation model
+*
+* Mutations are accepted in call order, coalesced for a short window, and
+* pushed by one worker. Only one batch is in flight at a time; mutations that
+* arrive during a push form the next batch. This serializes one backend
+* instance's writes while still reducing the number of Hub commits.
+*
+* Reads use an optimistic view: the last durable cache overlaid with the
+* in-flight batch and then the pending batch. A read can therefore observe an
+* accepted mutation before it is durable; a failed push invalidates that view
+* and the next operation reloads from Hub.
+*
+* A `409` parent conflict triggers an authoritative pull and rematerializes
+* the in-flight batch over the fetched tree before retrying. Edits replay their
+* original replacement intent; absolute writes, deletes, and uploads replay as
+* absolute changes. Retries are bounded by `MAX_CONFLICT_RETRIES`.
+*/
 var ContextHubBackend = class ContextHubBackend {
 	identifier;
 	client;
+	/** Last durable Hub file state; `null` means the next access must load it. */
 	cache = null;
 	linkedEntries = {};
+	/** Parent hash for the durable cache, used for optimistic-concurrency pushes. */
 	commitHash = null;
+	/** Shared cold-load promise so concurrent first operations perform one pull. */
+	loadPromise = null;
+	/** Promise chain serializing mutation acceptance and optimistic projections. */
+	mutationOrder = Promise.resolve();
+	/** Mutations accepted for the next coalesced push. */
+	pendingBatch = null;
+	/** The batch currently submitted to Hub and visible to optimistic reads. */
+	inFlightBatch = null;
+	/** The single queue-draining worker, when active. */
+	workerPromise = null;
+	/**
+	* Blocks cache consumers while a successful push without a parseable commit
+	* hash is being confirmed by an authoritative pull.
+	*/
+	snapshotPublication = null;
 	constructor(identifier, options = {}) {
 		this.identifier = identifier;
 		this.client = options.client ?? new langsmith.Client();
@@ -6638,49 +6784,319 @@ var ContextHubBackend = class ContextHubBackend {
 	static toHubUnavailableError(error) {
 		return `Hub unavailable: ${getErrorMessage(error)}`;
 	}
-	async loadTree() {
+	async fetchTree() {
 		let context;
 		try {
 			context = await this.client.pullAgent(this.identifier);
 		} catch (error) {
-			if (isLangSmithNotFoundError(error)) {
-				this.cache = {};
-				this.linkedEntries = {};
-				this.commitHash = null;
-				return;
-			}
+			if (isLangSmithNotFoundError(error)) return {
+				cache: {},
+				linkedEntries: {},
+				commitHash: null
+			};
 			throw error;
 		}
-		this.commitHash = context.commit_hash;
-		this.cache = {};
-		this.linkedEntries = {};
-		for (const [path, entry] of Object.entries(context.files)) if (entry.type === "file") this.cache[path] = entry.content;
-		else if ((entry.type === "agent" || entry.type === "skill") && typeof entry.repo_handle === "string") this.linkedEntries[path] = entry.repo_handle;
+		const cache = {};
+		const linkedEntries = {};
+		for (const [path, entry] of Object.entries(context.files)) if (entry.type === "file") cache[path] = entry.content;
+		else if ((entry.type === "agent" || entry.type === "skill") && typeof entry.repo_handle === "string") linkedEntries[path] = entry.repo_handle;
+		return {
+			cache,
+			linkedEntries,
+			commitHash: context.commit_hash
+		};
 	}
-	async ensureCache() {
-		if (this.cache === null) await this.loadTree();
+	publishSnapshot(snapshot) {
+		this.cache = snapshot.cache;
+		this.linkedEntries = snapshot.linkedEntries;
+		this.commitHash = snapshot.commitHash;
+	}
+	async loadTree() {
+		this.publishSnapshot(await this.fetchTree());
+	}
+	beginSnapshotPublication() {
+		if (this.snapshotPublication !== null) throw new Error("Context Hub snapshot publication is already pending");
+		this.snapshotPublication = new Deferred();
+	}
+	finishSnapshotPublication() {
+		const publication = this.snapshotPublication;
+		this.snapshotPublication = null;
+		publication?.resolve();
+	}
+	async ensureCacheLoaded() {
+		while (this.snapshotPublication !== null) await this.snapshotPublication;
+		if (this.cache === null) {
+			let loadPromise = this.loadPromise;
+			if (loadPromise === null) {
+				loadPromise = this.loadTree();
+				this.loadPromise = loadPromise;
+			}
+			try {
+				await loadPromise;
+			} finally {
+				if (this.loadPromise === loadPromise) this.loadPromise = null;
+			}
+		}
 		if (this.cache === null) throw new Error("Context Hub cache failed to initialize");
-		return this.cache;
-	}
-	async commit(changes) {
-		if (Object.keys(changes).length === 0) return;
-		const payload = {};
-		for (const [path, content] of Object.entries(changes)) payload[path] = content === null ? null : {
-			type: "file",
-			content
+	}
+	async ensureCache() {
+		await this.ensureCacheLoaded();
+		return this.visibleCache();
+	}
+	static applyChanges(cache, changes) {
+		const next = { ...cache };
+		for (const [path, content] of Object.entries(changes)) if (content === null) delete next[path];
+		else next[path] = content;
+		return next;
+	}
+	/**
+	* Build the read-your-writes view without publishing speculative data as the
+	* durable cache. Later batches overlay earlier ones, matching worker order.
+	*/
+	visibleCache() {
+		let visible = { ...this.cache ?? {} };
+		if (this.inFlightBatch !== null) visible = ContextHubBackend.applyChanges(visible, this.inFlightBatch.changes);
+		if (this.pendingBatch !== null) visible = ContextHubBackend.applyChanges(visible, this.pendingBatch.changes);
+		return visible;
+	}
+	invalidateCache() {
+		this.cache = null;
+		this.linkedEntries = {};
+		this.commitHash = null;
+		this.loadPromise = null;
+	}
+	async acquireMutationTurn() {
+		let release;
+		const previous = this.mutationOrder;
+		this.mutationOrder = new Promise((resolve) => {
+			release = resolve;
+		});
+		await previous;
+		return release;
+	}
+	/**
+	* Serialize validation and enqueueing so each operation is evaluated against
+	* a stable optimistic projection. Cache loading begins before acquiring the
+	* turn, allowing concurrent cold-start callers to share the same pull.
+	*/
+	async acceptMutation(operation) {
+		const turn = this.acquireMutationTurn();
+		const cacheOutcome = this.ensureCacheLoaded().then(() => ({ loaded: true }), (error) => ({
+			loaded: false,
+			error
+		}));
+		const release = await turn;
+		try {
+			const outcome = await cacheOutcome;
+			if (!outcome.loaded) throw outcome.error;
+			while (this.cache === null) await this.ensureCacheLoaded();
+			return operation(this.visibleCache());
+		} finally {
+			release();
+		}
+	}
+	/**
+	* Start a batch's coalescing window. The worker waits for this signal before
+	* detaching the batch; cancellation resolves it immediately so failures do
+	* not leave the worker waiting on a timer.
+	*/
+	createMutationBatch() {
+		const batch = {
+			changes: {},
+			waiters: [],
+			ready: new Deferred(),
+			timer: null
 		};
-		const url = await this.client.pushAgent(this.identifier, {
-			files: payload,
-			...this.commitHash ? { parentCommit: this.commitHash } : {}
+		batch.timer = setTimeout(() => {
+			batch.timer = null;
+			batch.ready.resolve();
+		}, MUTATION_COALESCE_MS);
+		return batch;
+	}
+	cancelBatchTimer(batch) {
+		if (batch.timer !== null) {
+			clearTimeout(batch.timer);
+			batch.timer = null;
+		}
+		batch.ready.resolve();
+	}
+	enqueueCommit(changes, intent = {
+		kind: "changes",
+		changes: { ...changes }
+	}) {
+		if (Object.keys(changes).length === 0) return Promise.resolve();
+		let batch = this.pendingBatch;
+		if (batch === null) {
+			batch = this.createMutationBatch();
+			this.pendingBatch = batch;
+		}
+		Object.assign(batch.changes, changes);
+		const completion = new Deferred();
+		batch.waiters.push({
+			intent,
+			completion
 		});
-		const match = URL_COMMIT_SUFFIX_RE.exec(url);
-		if (match) this.commitHash = match[1];
-		if (this.cache !== null) {
-			const deletions = new Set(Object.entries(changes).filter(([, content]) => content === null).map(([path]) => path));
-			const updates = Object.fromEntries(Object.entries(changes).filter((entry) => entry[1] !== null));
-			this.cache = {
-				...Object.fromEntries(Object.entries(this.cache).filter(([path]) => !deletions.has(path))),
-				...updates
+		this.startWorker();
+		return completion.promise;
+	}
+	/**
+	* Replay ordered intents over an authoritative base after a conflict. This
+	* rebuilds the push payload and optimistic overlay. An edit that no longer
+	* applies throws the supplied conflict error; absolute changes are reapplied.
+	*/
+	rematerializeBatch(batch, base, conflictError) {
+		let cache = { ...base };
+		const changes = {};
+		for (const waiter of batch.waiters) {
+			const { intent } = waiter;
+			if (intent.kind === "changes") {
+				Object.assign(changes, intent.changes);
+				cache = ContextHubBackend.applyChanges(cache, intent.changes);
+				continue;
+			}
+			const current = cache[intent.path];
+			if (current === void 0) throw conflictError;
+			const replacementResult = performStringReplacement(current, intent.oldString, intent.newString, intent.replaceAll);
+			if (typeof replacementResult === "string") throw conflictError;
+			const [newContent, occurrences] = replacementResult;
+			const editChanges = { [intent.path]: newContent };
+			Object.assign(changes, editChanges);
+			cache = ContextHubBackend.applyChanges(cache, editChanges);
+			intent.updateOccurrences(occurrences);
+		}
+		batch.changes = changes;
+		return cache;
+	}
+	rematerializeAfterConflict(batch, snapshot, conflictError) {
+		const cache = this.rematerializeBatch(batch, snapshot.cache, conflictError);
+		let pendingReplayError = null;
+		if (this.pendingBatch !== null) try {
+			this.rematerializeBatch(this.pendingBatch, cache, conflictError);
+		} catch (error) {
+			if (error !== conflictError) throw error;
+			pendingReplayError = error;
+		}
+		this.publishSnapshot(snapshot);
+		if (pendingReplayError !== null) this.failPendingBatch(pendingReplayError);
+	}
+	rematerializePendingBatch(snapshot) {
+		if (this.pendingBatch === null) return null;
+		const conflictError = createLangSmithConflictError("Pending Context Hub mutation conflicts with authoritative state");
+		try {
+			this.rematerializeBatch(this.pendingBatch, snapshot.cache, conflictError);
+			return null;
+		} catch (error) {
+			if (error !== conflictError) throw error;
+			return conflictError;
+		}
+	}
+	startWorker() {
+		if (this.workerPromise !== null) return;
+		const worker = this.drainMutationQueue().catch((error) => {
+			this.failAllBatches(error);
+		}).finally(() => {
+			if (this.workerPromise === worker) {
+				this.workerPromise = null;
+				if (this.pendingBatch !== null) this.startWorker();
+			}
+		});
+		this.workerPromise = worker;
+	}
+	/**
+	* Drain coalesced batches sequentially. A completed batch publishes durable
+	* state before settling its callers; a failed batch invalidates local state
+	* and rejects both in-flight and queued callers so the next mutation reloads.
+	*/
+	async drainMutationQueue() {
+		while (this.pendingBatch !== null) {
+			const batch = this.pendingBatch;
+			await batch.ready;
+			if (this.pendingBatch !== batch) continue;
+			this.pendingBatch = null;
+			this.inFlightBatch = batch;
+			let pendingReplayError = null;
+			try {
+				const result = await this.pushBatch(batch);
+				if (result.kind === "snapshot") {
+					pendingReplayError = this.rematerializePendingBatch(result.snapshot);
+					this.publishSnapshot(result.snapshot);
+				} else {
+					this.cache = ContextHubBackend.applyChanges(this.cache ?? {}, batch.changes);
+					this.commitHash = result.commitHash;
+				}
+			} catch (error) {
+				this.inFlightBatch = null;
+				this.invalidateCache();
+				this.finishSnapshotPublication();
+				for (const waiter of batch.waiters) waiter.completion.reject(error);
+				this.failPendingBatch(error);
+				return;
+			}
+			this.inFlightBatch = null;
+			this.finishSnapshotPublication();
+			for (const waiter of batch.waiters) waiter.completion.resolve();
+			if (pendingReplayError !== null) {
+				this.failPendingBatch(pendingReplayError);
+				return;
+			}
+		}
+	}
+	failPendingBatch(error) {
+		const pending = this.pendingBatch;
+		if (pending === null) return;
+		this.pendingBatch = null;
+		this.cancelBatchTimer(pending);
+		for (const waiter of pending.waiters) waiter.completion.reject(error);
+	}
+	failAllBatches(error) {
+		const inFlight = this.inFlightBatch;
+		this.inFlightBatch = null;
+		this.invalidateCache();
+		this.finishSnapshotPublication();
+		if (inFlight !== null) {
+			this.cancelBatchTimer(inFlight);
+			for (const waiter of inFlight.waiters) waiter.completion.reject(error);
+		}
+		this.failPendingBatch(error);
+	}
+	/**
+	* Push a materialized batch with the durable commit as its parent. On a 409,
+	* refresh Hub state, replay the batch, and retry with the new parent. A push
+	* response without a trustworthy hash is confirmed by a pull before callers
+	* are allowed to observe it as durable.
+	*/
+	async pushBatch(batch) {
+		for (let attempt = 0;; attempt += 1) {
+			const payload = {};
+			for (const [path, content] of Object.entries(batch.changes)) payload[path] = content === null ? null : {
+				type: "file",
+				content
+			};
+			let url;
+			try {
+				url = await this.client.pushAgent(this.identifier, {
+					files: payload,
+					...this.commitHash ? { parentCommit: this.commitHash } : {}
+				});
+			} catch (error) {
+				if (getLangSmithStatus(error) !== 409 || attempt >= MAX_CONFLICT_RETRIES) throw error;
+				const snapshot = await this.fetchTree();
+				this.rematerializeAfterConflict(batch, snapshot, error);
+				continue;
+			}
+			const pushedCommitHash = parseCommitHashFromUrl(url, this.identifier);
+			if (pushedCommitHash === null) {
+				this.beginSnapshotPublication();
+				const snapshot = await this.fetchTree();
+				if (snapshot.commitHash === null) throw new Error("Context Hub commit succeeded but its hash could not be resolved");
+				return {
+					kind: "snapshot",
+					snapshot
+				};
+			}
+			return {
+				kind: "commit",
+				commitHash: pushedCommitHash
 			};
 		}
 	}
@@ -6808,53 +7224,71 @@ var ContextHubBackend = class ContextHubBackend {
 	async write(filePath, content) {
 		const hubPath = ContextHubBackend.stripPrefix(filePath);
 		try {
-			await this.ensureCache();
-			await this.commit({ [hubPath]: content });
+			const accepted = await this.acceptMutation(() => {
+				return {
+					result: {
+						path: filePath,
+						filesUpdate: null
+					},
+					completion: this.enqueueCommit({ [hubPath]: content })
+				};
+			});
+			await accepted.completion;
+			return accepted.result;
 		} catch (error) {
-			if (isLangSmithError(error)) {
-				this.cache = null;
-				return { error: ContextHubBackend.toHubUnavailableError(error) };
-			}
+			if (isLangSmithError(error)) return { error: ContextHubBackend.toHubUnavailableError(error) };
 			throw error;
 		}
-		return {
-			path: filePath,
-			filesUpdate: null
-		};
 	}
 	async edit(filePath, oldString, newString, replaceAll = false) {
 		const hubPath = ContextHubBackend.stripPrefix(filePath);
 		try {
-			const current = (await this.ensureCache())[hubPath];
-			if (current === void 0) return { error: `Error: File '${filePath}' not found` };
-			const replacementResult = performStringReplacement(current, oldString, newString, replaceAll);
-			if (typeof replacementResult === "string") return { error: replacementResult };
-			const [newContent, occurrences] = replacementResult;
-			await this.commit({ [hubPath]: newContent });
-			return {
-				path: filePath,
-				filesUpdate: null,
-				occurrences
-			};
+			const accepted = await this.acceptMutation((cache) => {
+				const current = cache[hubPath];
+				if (current === void 0) return { result: { error: `Error: File '${filePath}' not found` } };
+				const replacementResult = performStringReplacement(current, oldString, newString, replaceAll);
+				if (typeof replacementResult === "string") return { result: { error: replacementResult } };
+				const [newContent, occurrences] = replacementResult;
+				const result = {
+					path: filePath,
+					filesUpdate: null,
+					occurrences
+				};
+				return {
+					result,
+					completion: this.enqueueCommit({ [hubPath]: newContent }, {
+						kind: "edit",
+						path: hubPath,
+						oldString,
+						newString,
+						replaceAll,
+						updateOccurrences: (replayedOccurrences) => {
+							result.occurrences = replayedOccurrences;
+						}
+					})
+				};
+			});
+			await accepted.completion;
+			return accepted.result;
 		} catch (error) {
-			if (isLangSmithError(error)) {
-				this.cache = null;
-				return { error: ContextHubBackend.toHubUnavailableError(error) };
-			}
+			if (isLangSmithError(error)) return { error: ContextHubBackend.toHubUnavailableError(error) };
 			throw error;
 		}
 	}
 	async delete(filePath) {
 		const hubPath = ContextHubBackend.stripPrefix(filePath);
 		try {
-			if (!(hubPath in await this.ensureCache())) return { error: `Error: File '${filePath}' not found` };
-			await this.commit({ [hubPath]: null });
-			return { path: filePath };
+			const accepted = await this.acceptMutation((cache) => {
+				if (!(hubPath in cache)) return { result: { error: `Error: File '${filePath}' not found` } };
+				return {
+					result: { path: filePath },
+					completion: this.enqueueCommit({ [hubPath]: null })
+				};
+			});
+			await accepted.completion;
+			return accepted.result;
 		} catch (error) {
-			if (isLangSmithError(error)) {
-				this.cache = null;
-				return { error: ContextHubBackend.toHubUnavailableError(error) };
-			}
+			if (isLangSmithError(error)) return { error: ContextHubBackend.toHubUnavailableError(error) };
 			throw error;
 		}
 	}
@@ -6871,13 +7305,15 @@ var ContextHubBackend = class ContextHubBackend {
 		}
 		let commitError = null;
 		if (Object.keys(validFiles).length > 0) try {
-			await this.ensureCache();
-			await this.commit(validFiles);
+			await (await this.acceptMutation(() => {
+				return {
+					result: null,
+					completion: this.enqueueCommit(validFiles)
+				};
+			})).completion;
 		} catch (error) {
-			if (isLangSmithError(error)) {
-				this.cache = null;
-				commitError = mapHubFileOperationError(error);
-			} else throw error;
+			if (isLangSmithError(error)) commitError = mapHubFileOperationError(error);
+			else throw error;
 		}
 		return decoded.map(([path, text]) => {
 			if (text === null) return {
@@ -7873,4 +8309,4 @@ Object.defineProperty(exports, "serializeProfile", {
 	}
 });
 
-//# sourceMappingURL=langsmith-D2d3Dwcc.cjs.map
+//# sourceMappingURL=langsmith-BJ2PdYqB.cjs.map