deepagents 1.14.1 → 1.15.0

package/dist/{langsmith-Bhg_Q4ZO.cjs → langsmith-DMOexB11.cjs}

@@ -21,20 +21,42 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 //#endregion
 let langchain = require("langchain");
+let _langchain_core_errors = require("@langchain/core/errors");
 let _langchain_langgraph = require("@langchain/langgraph");
 let zod_v4 = require("zod/v4");
 let micromatch = require("micromatch");
 micromatch = __toESM(micromatch, 1);
+let node_crypto = require("node:crypto");
 let _langchain_core_messages = require("@langchain/core/messages");
 let zod = require("zod");
 zod = __toESM(zod, 1);
-let _langchain_core_errors = require("@langchain/core/errors");
 let langchain_chat_models_universal = require("langchain/chat_models/universal");
 let yaml = require("yaml");
 yaml = __toESM(yaml, 1);
+let _langchain_core_runnables = require("@langchain/core/runnables");
+let _langchain_core_tools = require("@langchain/core/tools");
+let _langchain_core_language_models_base = require("@langchain/core/language_models/base");
+let _langchain_core_utils_function_calling = require("@langchain/core/utils/function_calling");
+let _langchain_core_utils_json_schema = require("@langchain/core/utils/json_schema");
+let _langchain_core_utils_types = require("@langchain/core/utils/types");
 let _langchain_langgraph_sdk = require("@langchain/langgraph-sdk");
 let langsmith = require("langsmith");
 let langsmith_experimental_sandbox = require("langsmith/experimental/sandbox");
+//#region src/backends/realpath.ts
+const REALPATH = Symbol.for("deepagents.realpath");
+function getRealpath(backend) {
+	if (typeof backend !== "object" || backend === null) return;
+	const fn = backend[REALPATH];
+	return typeof fn === "function" ? fn : void 0;
+}
+function setRealpath(target, fn) {
+	Object.defineProperty(target, REALPATH, {
+		value: fn,
+		enumerable: false,
+		configurable: true
+	});
+}
+//#endregion
 //#region src/backends/utils.ts
 /**
 * Shared utility functions for memory backend implementations.
@@ -657,9 +679,20 @@ function adaptBackendProtocol(backend) {
 			return result;
 		}
 	};
-	const routePrefixes = backend.routePrefixes;
-	if (Array.isArray(routePrefixes)) Object.defineProperty(adapted, "routePrefixes", {
-		value: routePrefixes,
+	const identityMarkers = [["routePrefixes", Array.isArray], ["backendKind", (value) => typeof value === "string"]];
+	for (const [key, isValid] of identityMarkers) {
+		const value = backend[key];
+		if (isValid(value)) Object.defineProperty(adapted, key, {
+			value,
+			enumerable: true,
+			configurable: true
+		});
+	}
+	const realpath = getRealpath(backend);
+	if (realpath !== void 0) setRealpath(adapted, realpath);
+	const resolveBackendForPath = backend.resolveBackendForPath;
+	if (typeof resolveBackendForPath === "function") Object.defineProperty(adapted, "resolveBackendForPath", {
+		value: (path) => resolveBackendForPath.call(backend, path),
 		enumerable: true,
 		configurable: true
 	});
@@ -810,8 +843,14 @@ const PREGEL_READ_KEY = "__pregel_read";
 * for the middleware to apply via Command.
 */
 var StateBackend = class {
+	/** Class identity discriminant for {@link StateBackend.isInstance}. */
+	backendKind = "state";
 	runtime;
 	fileFormat;
+	/** Duck-typed so this survives the plain-object copies `adaptBackendProtocol` makes — a class check wouldn't. */
+	static isInstance(backend) {
+		return typeof backend === "object" && backend !== null && backend.backendKind === "state";
+	}
 	constructor(runtimeOrOptions, options) {
 		if (runtimeOrOptions != null && typeof runtimeOrOptions === "object" && "state" in runtimeOrOptions) {
 			this.runtime = runtimeOrOptions;
@@ -1111,6 +1150,466 @@ var StateBackend = class {
 	}
 };
 //#endregion
+//#region src/middleware/blobOffload.ts
+/**
+* Content-addressed offload of binary `read_file` and inline `HumanMessage`
+* blocks to the backend.
+*
+* Binary blocks are written to `/blobs/<sha256>` and replaced in state with a
+* `deepagents_blob` reference. Model requests are rehydrated from the backend
+* (or a per-run cache), so checkpoints never carry the base64 payload.
+*/
+/** Content block key holding the SHA-256 digest of an offloaded payload. */
+const BLOB_REF_KEY = "deepagents_blob";
+const MISSING_BLOB_TEXT = "[Binary content from an earlier read_file call is no longer available. Re-read the file if you still need it.]";
+const DIGEST_RE = /^[0-9a-f]{64}$/;
+const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
+/** Whether `reference` is a well-formed digest string. */
+function isDigest(reference) {
+	return typeof reference === "string" && DIGEST_RE.test(reference);
+}
+function isValidBase64(value) {
+	return value.length > 0 && value.length % 4 === 0 && BASE64_RE.test(value);
+}
+function sha256Hex(bytes) {
+	return (0, node_crypto.createHash)("sha256").update(bytes).digest("hex");
+}
+const DEFAULT_BLOB_CACHE_BYTES = 268435456;
+/**
+* Content-addressed cache of base64 payloads, bounded by total payload size
+* (LRU-evicted past the bound). Safe to share across threads — every key is
+* a SHA-256 digest of its own value, so a hit is only reachable by a caller
+* who already has that exact reference, and an eviction just forces a
+* re-fetch from the backend, never a wrong result.
+*/
+var BlobCache = class extends Map {
+	maxBytes;
+	totalBytes = 0;
+	constructor(maxBytes = DEFAULT_BLOB_CACHE_BYTES) {
+		super();
+		this.maxBytes = maxBytes;
+	}
+	/** Returns the cached payload for `digest`, marking it most recently used. */
+	get(digest) {
+		const payload = super.get(digest);
+		if (payload === void 0) return void 0;
+		super.delete(digest);
+		super.set(digest, payload);
+		return payload;
+	}
+	/** Caches `payload`, evicting least-recently-used entries past the size bound. */
+	set(digest, payload) {
+		if (payload.length > this.maxBytes) return this;
+		const previous = super.get(digest);
+		if (previous !== void 0) {
+			this.totalBytes -= previous.length;
+			super.delete(digest);
+		}
+		super.set(digest, payload);
+		this.totalBytes += payload.length;
+		while (this.totalBytes > this.maxBytes) {
+			const oldestDigest = this.keys().next().value;
+			if (oldestDigest === void 0) break;
+			const oldest = super.get(oldestDigest);
+			super.delete(oldestDigest);
+			this.totalBytes -= oldest?.length ?? 0;
+		}
+		return this;
+	}
+};
+function blobPath(prefix, digest) {
+	return `${prefix}/${digest}`;
+}
+function contentBlocks(message) {
+	const content = message?.content;
+	return Array.isArray(content) ? content : null;
+}
+/** Map each inline base64 payload found in `messages` to its digest and decoded bytes. */
+function pendingBlobs(messages) {
+	const pending = /* @__PURE__ */ new Map();
+	for (const message of messages) {
+		const blocks = contentBlocks(message);
+		if (!blocks) continue;
+		for (const block of blocks) {
+			if (block == null || typeof block !== "object") continue;
+			const payload = block.data;
+			if (typeof payload !== "string" || pending.has(payload) || !isValidBase64(payload)) continue;
+			let raw;
+			try {
+				raw = new Uint8Array(Buffer.from(payload, "base64"));
+			} catch {
+				continue;
+			}
+			pending.set(payload, {
+				digest: sha256Hex(raw),
+				raw
+			});
+		}
+	}
+	return pending;
+}
+/** Replace payloads found in `digests` with blob references; returns `messages` unchanged if nothing matched. */
+function stubMessages(messages, digests) {
+	return messages.map((message) => {
+		const blocks = contentBlocks(message);
+		if (!blocks) return message;
+		let changed = false;
+		const newContent = blocks.map((block) => {
+			const digest = typeof block.data === "string" ? digests.get(block.data) : void 0;
+			if (digest === void 0) return block;
+			changed = true;
+			const { data: _data, ...rest } = block;
+			return {
+				...rest,
+				[BLOB_REF_KEY]: digest
+			};
+		});
+		if (!changed) return message;
+		return withContent(message, newContent);
+	});
+}
+/**
+* Upload inline binary payloads found in `messages` and return messages carrying blob
+* references instead. Payloads that fail to upload stay inline — offload is best-effort.
+*/
+async function offloadMessages(messages, backend, prefix, cache) {
+	const pending = pendingBlobs(messages);
+	if (pending.size === 0) return [...messages];
+	if (typeof backend.uploadFiles !== "function") {
+		console.warn("Backend does not support uploadFiles; binary read_file content stays inline");
+		return [...messages];
+	}
+	const entries = [...pending.entries()];
+	let responses;
+	try {
+		responses = await backend.uploadFiles(entries.map(([, { digest, raw }]) => [blobPath(prefix, digest), raw]));
+	} catch (error) {
+		console.warn("Failed to offload binary read_file content; keeping it inline", error);
+		return [...messages];
+	}
+	const digests = /* @__PURE__ */ new Map();
+	entries.forEach(([payload, { digest }], index) => {
+		if (responses[index]?.error == null) {
+			digests.set(payload, digest);
+			cache.set(digest, payload);
+		}
+	});
+	return stubMessages(messages, digests);
+}
+/** Apply `offloadMessages` to a tool result (a `ToolMessage`, or a `Command`-shaped update). */
+async function offloadToolResult(result, backend, prefix, cache) {
+	if (langchain.ToolMessage.isInstance(result)) return (await offloadMessages([result], backend, prefix, cache))[0];
+	const update = result?.update;
+	if (update && Array.isArray(update.messages)) {
+		const messages = await offloadMessages(update.messages, backend, prefix, cache);
+		return new _langchain_langgraph.Command({
+			...result,
+			update: {
+				...update,
+				messages
+			}
+		});
+	}
+	return result;
+}
+/** Return `HumanMessage`s with ids after the last `AIMessage`, preferring a version already queued in `pending`. */
+function humanCandidates({ stateMessages, pending }) {
+	let lastAiIndex = -1;
+	stateMessages.forEach((message, index) => {
+		if (langchain.AIMessage.isInstance(message)) lastAiIndex = index;
+	});
+	const queued = /* @__PURE__ */ new Map();
+	for (const message of pending) {
+		const id = message?.id;
+		if (typeof id === "string") queued.set(id, message);
+	}
+	const candidates = [];
+	for (const message of stateMessages.slice(lastAiIndex + 1)) {
+		if (!langchain.HumanMessage.isInstance(message) || typeof message.id !== "string") continue;
+		candidates.push(queued.get(message.id) ?? message);
+	}
+	return candidates;
+}
+function mergeReplacements({ pending, offloaded, candidates }) {
+	const replaced = offloaded.filter((next, index) => next !== candidates[index]);
+	const replacedIds = new Set(replaced.map((message) => message?.id));
+	return [...pending.filter((message) => !replacedIds.has(message?.id)), ...replaced];
+}
+/** Return `pending` plus stubbed replacements for `HumanMessage`s in state carrying inline media. */
+async function offloadHumanMessages({ stateMessages, pending }, backend, prefix, cache) {
+	const candidates = humanCandidates({
+		stateMessages,
+		pending
+	});
+	if (candidates.length === 0) return [...pending];
+	return mergeReplacements({
+		pending,
+		offloaded: await offloadMessages(candidates, backend, prefix, cache),
+		candidates
+	});
+}
+/** Collect every well-formed `deepagents_blob` digest referenced in `messages`, deduplicated. */
+function referencedDigests(messages) {
+	const digests = /* @__PURE__ */ new Set();
+	for (const message of messages) {
+		const blocks = contentBlocks(message);
+		if (!blocks) continue;
+		for (const block of blocks) {
+			const ref = block?.[BLOB_REF_KEY];
+			if (isDigest(ref)) digests.add(ref);
+		}
+	}
+	return [...digests];
+}
+function cachedPayloads(digests, cache) {
+	const payloads = /* @__PURE__ */ new Map();
+	const missing = [];
+	for (const digest of digests) {
+		const payload = cache.get(digest);
+		if (payload !== void 0) payloads.set(digest, payload);
+		else missing.push(digest);
+	}
+	return {
+		payloads,
+		missing
+	};
+}
+/** Verify each downloaded blob's integrity before trusting it — blobs live on an agent-writable backend. */
+function acceptDownloads(missing, responses, payloads, cache) {
+	missing.forEach((digest, index) => {
+		const response = responses[index];
+		if (!response || response.error != null || response.content == null) return;
+		if (sha256Hex(response.content) !== digest) return;
+		const payload = Buffer.from(response.content).toString("base64");
+		cache.set(digest, payload);
+		payloads.set(digest, payload);
+	});
+}
+function messageHasRefs(message) {
+	const blocks = contentBlocks(message);
+	return blocks != null && blocks.some((block) => block != null && typeof block === "object" && "deepagents_blob" in block);
+}
+function withContent(message, content) {
+	if (langchain.ToolMessage.isInstance(message)) return new langchain.ToolMessage({
+		content,
+		tool_call_id: message.tool_call_id,
+		name: message.name,
+		id: message.id,
+		artifact: message.artifact,
+		status: message.status,
+		additional_kwargs: message.additional_kwargs,
+		response_metadata: message.response_metadata,
+		metadata: message.metadata
+	});
+	if (langchain.HumanMessage.isInstance(message)) return new langchain.HumanMessage({
+		content,
+		id: message.id,
+		additional_kwargs: message.additional_kwargs,
+		response_metadata: message.response_metadata
+	});
+	if (langchain.AIMessage.isInstance(message)) return new langchain.AIMessage({
+		content,
+		id: message.id,
+		tool_calls: message.tool_calls,
+		invalid_tool_calls: message.invalid_tool_calls,
+		usage_metadata: message.usage_metadata,
+		additional_kwargs: message.additional_kwargs,
+		response_metadata: message.response_metadata
+	});
+	if (langchain.SystemMessage.isInstance(message)) return new langchain.SystemMessage({
+		content,
+		id: message.id,
+		additional_kwargs: message.additional_kwargs,
+		response_metadata: message.response_metadata
+	});
+	console.warn(`blobOffload: left a blob reference unresolved on an unsupported message type (${message?.constructor?.name})`);
+	return message;
+}
+/** Restore base64 payloads for blob references; a reference with no matching payload becomes a text notice. */
+function restorePayloads(messages, payloads) {
+	const hydrate = (block) => {
+		const ref = block[BLOB_REF_KEY];
+		if (ref === void 0) return block;
+		const payload = isDigest(ref) ? payloads.get(ref) : void 0;
+		if (payload === void 0) return {
+			type: "text",
+			text: MISSING_BLOB_TEXT
+		};
+		const { [BLOB_REF_KEY]: _ref, ...rest } = block;
+		return {
+			...rest,
+			data: payload
+		};
+	};
+	return messages.map((message) => {
+		if (!messageHasRefs(message)) return message;
+		return withContent(message, (contentBlocks(message) ?? []).map(hydrate));
+	});
+}
+/**
+* Restore base64 payloads for blob references ahead of a model call.
+*
+* Only the returned array is used for the request — callers must not persist
+* the result back into state, or the checkpoint-size benefit of offloading is
+* lost the next time state is saved.
+*/
+async function hydrateMessages(messages, backend, prefix, cache) {
+	if (!messages.some(messageHasRefs)) return [...messages];
+	const { payloads, missing } = cachedPayloads(referencedDigests(messages), cache);
+	if (missing.length > 0) if (typeof backend.downloadFiles !== "function") console.warn("Backend does not support downloadFiles; offloaded read_file content is unavailable");
+	else {
+		let responses = [];
+		try {
+			responses = await backend.downloadFiles(missing.map((digest) => blobPath(prefix, digest)));
+		} catch (error) {
+			console.warn("Failed to load offloaded read_file content", error);
+		}
+		acceptDownloads(missing, responses, payloads, cache);
+	}
+	return restorePayloads(messages, payloads);
+}
+//#endregion
+//#region src/middleware/unsupportedContent.ts
+const PDF_MIME_TYPE = "application/pdf";
+/** Content block types `read_file` may emit that require multimodal model support. */
+const MULTIMODAL_BLOCK_TYPES = /* @__PURE__ */ new Set([
+	"image",
+	"audio",
+	"video",
+	"file"
+]);
+const PROFILE_FIELD_BY_BLOCK_TYPE = {
+	image: "imageInputs",
+	audio: "audioInputs",
+	video: "videoInputs"
+};
+const TOOL_MESSAGE_FIELD_BY_BLOCK_TYPE = { image: "imageToolMessage" };
+function hasInlineData(block) {
+	return block.data != null || block.source_type === "base64";
+}
+function blockMimeType(block) {
+	const mimeType = block.mimeType ?? block.mime_type;
+	return typeof mimeType === "string" ? mimeType : void 0;
+}
+/**
+* Unlike the other block types, a missing `fileMimeTypes` defaults to
+* unsupported rather than supported: generic file support varies far more
+* across models than image/audio/video, so there's no safe assumption to
+* fall back on absent real profile data.
+*/
+function fileBlockSupported(block, profile, inToolMessage) {
+	if (!hasInlineData(block)) return true;
+	const mimeType = blockMimeType(block);
+	if (mimeType === PDF_MIME_TYPE) {
+		if (inToolMessage && profile.pdfToolMessage !== void 0) return profile.pdfToolMessage !== false;
+		return profile.pdfInputs !== false;
+	}
+	if (mimeType == null) return false;
+	const { fileMimeTypes } = profile;
+	return Array.isArray(fileMimeTypes) && fileMimeTypes.includes(mimeType);
+}
+/**
+* Whether the model accepts a multimodal block.
+*
+* Missing profile fields default to supported, since profile coverage is
+* incomplete — except `file` blocks, where a missing `fileMimeTypes`
+* defaults to unsupported (see `fileBlockSupported`).
+*/
+function multimodalBlockSupported(block, profile, inToolMessage) {
+	if (block.type === "file") return fileBlockSupported(block, profile, inToolMessage);
+	const field = PROFILE_FIELD_BY_BLOCK_TYPE[block.type];
+	if (field == null) return true;
+	if (inToolMessage) {
+		const toolField = TOOL_MESSAGE_FIELD_BY_BLOCK_TYPE[block.type];
+		if (toolField != null && profile[toolField] !== void 0) return profile[toolField] !== false;
+	}
+	return profile[field] !== false;
+}
+function placeholder(block, path) {
+	return {
+		type: "text",
+		text: `[read_file: ${path ?? "the requested file"} was not attached because this model does not support ${block.type} content (${blockMimeType(block) ?? "unknown"}).]`
+	};
+}
+function readFilePaths(messages) {
+	const paths = /* @__PURE__ */ new Map();
+	for (const message of messages) {
+		if (!_langchain_core_messages.AIMessage.isInstance(message)) continue;
+		for (const toolCall of message.tool_calls ?? []) {
+			const path = toolCall.args?.file_path;
+			if (toolCall.id != null && typeof path === "string") paths.set(toolCall.id, path);
+		}
+	}
+	return paths;
+}
+/**
+* Without this, a request carrying content the model can't accept (e.g. a
+* `.zip` file sent to a model without file support) fails with a
+* non-retryable 400, and since the content stays in history, every later
+* turn fails the same way. Only the request is changed; messages in state
+* are left untouched, so switching to a model that accepts the content
+* sends it again.
+*/
+function scrubUnsupportedMultimodalContent(messages, model) {
+	const rawProfile = model?.profile;
+	const profile = rawProfile != null && typeof rawProfile === "object" ? rawProfile : {};
+	let paths;
+	let changed = false;
+	const result = messages.map((message) => {
+		const isTool = _langchain_core_messages.ToolMessage.isInstance(message);
+		if (!isTool && !_langchain_core_messages.HumanMessage.isInstance(message)) return message;
+		let messageChanged = false;
+		const content = message.contentBlocks.map((block) => {
+			if (block == null || typeof block !== "object" || !MULTIMODAL_BLOCK_TYPES.has(block.type) || multimodalBlockSupported(block, profile, isTool)) return block;
+			messageChanged = true;
+			paths ??= readFilePaths(messages);
+			return placeholder(block, isTool ? paths.get(message.tool_call_id) : void 0);
+		});
+		if (!messageChanged) return message;
+		changed = true;
+		if (isTool) return new _langchain_core_messages.ToolMessage({
+			content,
+			tool_call_id: message.tool_call_id,
+			name: message.name,
+			id: message.id,
+			artifact: message.artifact,
+			status: message.status,
+			metadata: message.metadata,
+			additional_kwargs: message.additional_kwargs,
+			response_metadata: message.response_metadata
+		});
+		return new _langchain_core_messages.HumanMessage({
+			content,
+			name: message.name,
+			id: message.id,
+			additional_kwargs: message.additional_kwargs,
+			response_metadata: message.response_metadata
+		});
+	});
+	return changed ? result : messages;
+}
+/**
+* Support is read from `model.profile` (see
+* https://docs.langchain.com/oss/javascript/langchain/models#model-profiles).
+*
+* Place this middleware last in the agent's `middleware` list, so that if
+* some other middleware changes `request.model`, this one sees the model
+* that will actually receive the request.
+*/
+function createUnsupportedContentMiddleware() {
+	return (0, langchain.createMiddleware)({
+		name: "UnsupportedContentMiddleware",
+		wrapModelCall: async (request, handler) => {
+			const messages = scrubUnsupportedMultimodalContent(request.messages, request.model);
+			if (messages === request.messages) return handler(request);
+			return handler({
+				...request,
+				messages
+			});
+		}
+	});
+}
+//#endregion
 //#region src/permissions/enforce.ts
 /**
 * Validate permission rule paths at setup time. Throws if any path is
@@ -1127,11 +1626,13 @@ function validatePermissionPaths(permissions) {
 * - Non-absolute paths (must start with `/`)
 * - Paths containing `..`
 * - Paths containing `~`
+*
+* Empty and `.` segments are dropped (`/a/./b` and `/a//b` become `/a/b`).
 */
 function validatePath(raw) {
 	if (typeof raw !== "string" || raw.length === 0) throw new Error("path must be a non-empty string");
 	if (!raw.startsWith("/")) throw new Error(`path must be absolute: ${JSON.stringify(raw)}`);
-	const segments = raw.split("/").filter((s) => s.length > 0);
+	const segments = raw.split("/").filter((s) => s.length > 0 && s !== ".");
 	if (segments.includes("..")) throw new Error(`path must not contain "..": ${JSON.stringify(raw)}`);
 	if (segments.includes("~")) throw new Error(`path must not contain "~": ${JSON.stringify(raw)}`);
 	return `/${segments.join("/")}`;
@@ -1181,14 +1682,15 @@ var CompositeBackend = class {
 	sortedRoutes;
 	constructor(defaultBackend, routes) {
 		this.default = isSandboxProtocol(defaultBackend) ? adaptSandboxProtocol(defaultBackend) : adaptBackendProtocol(defaultBackend);
-		this.routes = Object.fromEntries(Object.entries(routes).map(([k, v]) => [k, isSandboxProtocol(v) ? adaptSandboxProtocol(v) : adaptBackendProtocol(v)]));
+		this.routes = Object.fromEntries(Object.entries(routes).map(([k, v]) => [k.endsWith("/") ? k : `${k}/`, isSandboxProtocol(v) ? adaptSandboxProtocol(v) : adaptBackendProtocol(v)]));
 		this.sortedRoutes = Object.entries(this.routes).sort((a, b) => b[0].length - a[0].length);
+		setRealpath(this, (path) => this.resolveRealPath(path));
 	}
 	/** Delegates to default backend's id if it is a sandbox, otherwise empty string. */
 	get id() {
 		return isSandboxBackend(this.default) ? this.default.id : "";
 	}
-	/** Route prefixes registered on this backend (e.g. `["/workspace"]`). */
+	/** Route prefixes registered on this backend, normalized to a trailing slash (e.g. `["/workspace/"]`). */
 	get routePrefixes() {
 		return Object.keys(this.routes);
 	}
@@ -1202,6 +1704,28 @@ var CompositeBackend = class {
 		return typeof backend === "object" && backend !== null && Array.isArray(backend.routePrefixes);
 	}
 	/**
+	* Returns the backend for `path`, with the matched prefix stripped (`/foo` → `/`).
+	* Routes match on path-segment boundaries: `/foo` matches `/foo/bar` but not `/foobar`.
+	*/
+	resolveBackendForPath(path) {
+		return this.getBackendAndKey(path);
+	}
+	/**
+	* Resolve symlinks via the backend that owns `path`, re-adding the route
+	* prefix. Returns `path` unchanged when that backend has no realpath hook.
+	*/
+	async resolveRealPath(path) {
+		for (const [routePrefix, backend] of this.sortedRoutes) if (this.isPathWithinRoute(path, routePrefix)) {
+			const realpath = getRealpath(backend);
+			if (realpath === void 0) return path;
+			const suffix = path.substring(routePrefix.length);
+			const resolved = await realpath(suffix ? "/" + suffix : "/");
+			return routePrefix.slice(0, -1) + resolved;
+		}
+		const realpath = getRealpath(this.default);
+		return realpath === void 0 ? path : await realpath(path);
+	}
+	/**
 	* Determine which backend handles this key and strip prefix.
 	*
 	* @param key - Original file path
@@ -1805,6 +2329,8 @@ const GREP_TRUNCATION_NOTE = "Note: the search stopped early because it hit the
 * Set to null to disable the cap.
 */
 const DEFAULT_GREP_MAX_COUNT = 1e3;
+/** Path prefix offloaded binary content blobs are written under. */
+const BLOBS_PREFIX = "/blobs";
 /**
 * Message template for evicted tool results.
 */
@@ -1966,25 +2492,42 @@ function getErrorMessage$1(error) {
 	return String(error);
 }
 /**
-* Check whether `path` is permitted under `rules` for `operation`, returning an
-* error string to surface to the model (or `undefined` when allowed).
+* Resolve `canonical` through the backend's realpath hook, when it has one, and
+* re-validate the result so it is canonical for rule matching. Returns
+* `canonical` unchanged for backends without path aliasing.
+*/
+async function resolveRealPath(backend, canonical) {
+	const realpath = getRealpath(backend);
+	return realpath ? validatePath(await realpath(canonical)) : canonical;
+}
+/**
+* Check whether `path` is permitted under `rules` for `operation`.
+*
+* Returns the canonical path to hand the backend, or an error string to
+* surface to the model. The decision covers every form of the target: the
+* lexical canonical path (dot and empty segments dropped) and, when the
+* backend has a realpath hook, the symlink-resolved path it would actually
+* touch. A deny on either blocks the call.
 *
-* Never throws: an invalid path (non-absolute, or containing `..` or `~`) or a
-* denied path is a recoverable tool error, not a fatal run-ending one. Such
-* paths are rejected, never normalized, so they cannot bypass a deny rule or
-* reach the backend.
+* Never throws: an invalid path (non-absolute, or containing `..` or `~`), one
+* the backend cannot resolve, or a denied one is a recoverable tool error, not
+* a fatal run-ending one. With no rules configured, `path` is returned as-is.
 *
 * @internal
 */
-function checkPermission(rules, operation, path) {
-	if (rules.length === 0) return;
+async function checkPermission(backend, rules, operation, path) {
+	if (rules.length === 0) return { path };
 	let canonical;
+	let real;
 	try {
 		canonical = validatePath(path);
+		if (decidePathAccess(rules, operation, canonical) === "deny") return { error: `Error: permission denied for ${operation} on ${canonical}` };
+		real = await resolveRealPath(backend, canonical);
 	} catch (error) {
-		return `Error: ${getErrorMessage$1(error)}`;
+		return { error: `Error: ${getErrorMessage$1(error)}` };
 	}
-	if (decidePathAccess(rules, operation, canonical) === "deny") return `Error: permission denied for ${operation} on ${canonical}`;
+	if (real !== canonical && decidePathAccess(rules, operation, real) === "deny") return { error: `Error: permission denied for ${operation} on ${canonical} (resolves to ${real})` };
+	return { path: canonical };
 }
 /**
 * Build an error {@link ToolMessage} for a rejected or denied path. Returning a
@@ -2157,27 +2700,56 @@ function parentPath(path) {
 	if (parts.length <= 1) return "/";
 	return `/${parts.slice(0, -1).join("/")}`;
 }
+/**
+* Resolve the path a delete of `target` would actually remove. Backends unlink
+* a symlink leaf rather than following it, so only the parent is resolved.
+*/
+async function resolveDeleteRealPath(backend, target) {
+	const parts = posixParts(target);
+	if (parts.length === 0) return resolveRealPath(backend, target);
+	return validatePath(`${await resolveRealPath(backend, parentPath(target))}/${parts[parts.length - 1]}`);
+}
 function supportsDelete(backend) {
 	return typeof backend.delete === "function";
 }
 /**
 * Filter a list of filesystem entries to those the rules permit.
 *
-* `getPath` extracts the absolute path from each entry. Entries with
-* unparsable paths are included (not silently dropped). Returns the
-* original array unchanged when `rules` is empty.
+* `getPath` extracts the absolute path from each entry. Each entry is checked
+* on its canonical path and, when the backend has a realpath hook, on its
+* symlink-resolved path. Entries with unparsable paths are included; entries
+* whose path cannot be resolved are dropped.
+* Returns the original array unchanged when `rules` is empty.
 *
 * @internal
 */
-function filterByPermissions(entries, rules, operation, getPath) {
+async function filterByPermissions(backend, entries, rules, operation, getPath) {
 	if (rules.length === 0) return entries;
-	return entries.filter((entry) => {
+	const decisions = /* @__PURE__ */ new Map();
+	const isPermitted = async (rawPath) => {
+		let canonical;
 		try {
-			return decidePathAccess(rules, operation, validatePath(getPath(entry))) !== "deny";
+			canonical = validatePath(rawPath);
 		} catch {
 			return true;
 		}
-	});
+		if (decidePathAccess(rules, operation, canonical) === "deny") return false;
+		try {
+			return decidePathAccess(rules, operation, await resolveRealPath(backend, canonical)) !== "deny";
+		} catch {
+			return false;
+		}
+	};
+	const permitted = await Promise.all(entries.map((entry) => {
+		const rawPath = getPath(entry);
+		let decision = decisions.get(rawPath);
+		if (decision === void 0) {
+			decision = isPermitted(rawPath);
+			decisions.set(rawPath, decision);
+		}
+		return decision;
+	}));
+	return entries.filter((_, index) => permitted[index]);
 }
 const LS_TOOL_DESCRIPTION = langchain.context`
   Lists all files in a directory.
@@ -2265,13 +2837,13 @@ function getExecuteToolDescription(hasGrep, hasGlob) {
 function createLsTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return (0, langchain.tool)(async (input, runtime) => {
-		const permissionError = checkPermission(permissions, "read", input.path ?? "/");
-		if (permissionError !== void 0) return toolError(runtime, "ls", permissionError);
 		const resolvedBackend = await resolveBackend(backend, runtime);
 		const path = input.path || "/";
-		const lsResult = await resolvedBackend.ls(path);
+		const permission = await checkPermission(resolvedBackend, permissions, "read", path);
+		if (permission.error !== void 0) return toolError(runtime, "ls", permission.error);
+		const lsResult = await resolvedBackend.ls(permission.path);
 		if (lsResult.error) return `Error listing files: ${lsResult.error}`;
-		const infos = filterByPermissions(lsResult.files ?? [], permissions, "read", (info) => info.path);
+		const infos = await filterByPermissions(resolvedBackend, lsResult.files ?? [], permissions, "read", (info) => info.path);
 		if (infos.length === 0) return `No files found in ${path}`;
 		const lines = [];
 		for (const info of infos) if (info.is_dir) lines.push(`${info.path} (directory)`);
@@ -2294,23 +2866,17 @@ function createLsTool(backend, options) {
 function createReadFileTool(backend, options) {
 	const { customDescription, toolTokenLimitBeforeEvict, permissions } = options;
 	return (0, langchain.tool)(async (input, runtime) => {
-		const permissionError = checkPermission(permissions, "read", input.file_path);
-		if (permissionError !== void 0) return toolError(runtime, "read_file", permissionError);
 		const resolvedBackend = await resolveBackend(backend, runtime);
+		const permission = await checkPermission(resolvedBackend, permissions, "read", input.file_path);
+		if (permission.error !== void 0) return toolError(runtime, "read_file", permission.error);
 		const { file_path, offset: requestedOffset = 0, limit: requestedLimit = 100 } = input;
 		const { offset, limit } = normalizeReadPagination(requestedOffset, requestedLimit);
-		const readResult = await resolvedBackend.read(file_path, offset, limit);
-		if (readResult.error) return [{
-			type: "text",
-			text: `Error: ${readResult.error}`
-		}];
+		const readResult = await resolvedBackend.read(permission.path, offset, limit);
+		if (readResult.error) return toolError(runtime, "read_file", `Error: ${readResult.error}`);
 		const mimeType = readResult.mimeType ?? getMimeType(file_path);
 		if (!isTextMimeType(mimeType)) {
 			const binaryContent = readResult.content;
-			if (!binaryContent) return [{
-				type: "text",
-				text: `Error: expected binary content for '${file_path}'`
-			}];
+			if (!binaryContent) return toolError(runtime, "read_file", `Error: expected binary content for '${file_path}'`);
 			let base64Data;
 			if (typeof binaryContent === "string") base64Data = binaryContent;
 			else if (ArrayBuffer.isView(binaryContent)) base64Data = Buffer.from(binaryContent).toString("base64");
@@ -2319,10 +2885,7 @@ function createReadFileTool(backend, options) {
 				base64Data = Buffer.from(new Uint8Array(values)).toString("base64");
 			}
 			const sizeBytes = Math.ceil(base64Data.length * 3 / 4);
-			if (sizeBytes > 10485760) return [{
-				type: "text",
-				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 (sizeBytes > 10485760) return toolError(runtime, "read_file", `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",
 				mimeType,
@@ -2388,11 +2951,11 @@ function createReadFileTool(backend, options) {
 function createWriteFileTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return (0, langchain.tool)(async (input, runtime) => {
-		const permissionError = checkPermission(permissions, "write", input.file_path);
-		if (permissionError !== void 0) return toolError(runtime, "write_file", permissionError);
 		const resolvedBackend = await resolveBackend(backend, runtime);
+		const permission = await checkPermission(resolvedBackend, permissions, "write", input.file_path);
+		if (permission.error !== void 0) return toolError(runtime, "write_file", permission.error);
 		const { file_path, content } = input;
-		const result = await resolvedBackend.write(file_path, content);
+		const result = await resolvedBackend.write(permission.path, content);
 		if (result.error) return result.error;
 		const message = new langchain.ToolMessage({
 			content: `Successfully wrote to '${file_path}'`,
@@ -2420,11 +2983,11 @@ function createWriteFileTool(backend, options) {
 function createEditFileTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return (0, langchain.tool)(async (input, runtime) => {
-		const permissionError = checkPermission(permissions, "write", input.file_path);
-		if (permissionError !== void 0) return toolError(runtime, "edit_file", permissionError);
 		const resolvedBackend = await resolveBackend(backend, runtime);
+		const permission = await checkPermission(resolvedBackend, permissions, "write", input.file_path);
+		if (permission.error !== void 0) return toolError(runtime, "edit_file", permission.error);
 		const { file_path, old_string, new_string, replace_all = false } = input;
-		const result = await resolvedBackend.edit(file_path, old_string, new_string, replace_all);
+		const result = await resolvedBackend.edit(permission.path, old_string, new_string, replace_all);
 		if (result.error) return result.error;
 		const message = new langchain.ToolMessage({
 			content: `Successfully replaced ${result.occurrences} occurrence(s) in '${file_path}'`,
@@ -2464,6 +3027,17 @@ function createDeleteTool(backend, options) {
 		const hasDescendants = await deleteTargetMayHaveDescendants(resolvedBackend, validatedPath, permissions.length > 0);
 		const denyingPatterns = findDeleteDenyPatterns(permissions, validatedPath, hasDescendants);
 		if (denyingPatterns.length > 0) return toolError(runtime, "delete", `Error: permission denied for write on ${validatedPath} (matches deny rule(s): ${denyingPatterns.join(", ")})`);
+		if (permissions.length > 0) {
+			let realTarget;
+			try {
+				realTarget = await resolveDeleteRealPath(resolvedBackend, validatedPath);
+			} catch (error) {
+				return toolError(runtime, "delete", `Error: ${getErrorMessage$1(error)}`);
+			}
+			if (realTarget !== validatedPath) {
+				if (findDeleteDenyPatterns(permissions, realTarget, hasDescendants).length > 0) return toolError(runtime, "delete", `Error: permission denied for write on ${validatedPath} (resolves to ${realTarget})`);
+			}
+		}
 		if (!supportsDelete(resolvedBackend)) return toolError(runtime, "delete", `Error: deletion is not available for '${validatedPath}'.`);
 		const result = await resolvedBackend.delete(validatedPath);
 		if (result.error) return toolError(runtime, "delete", result.error);
@@ -2490,13 +3064,13 @@ function createDeleteTool(backend, options) {
 function createGlobTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return (0, langchain.tool)(async (input, runtime) => {
-		const permissionError = checkPermission(permissions, "read", input.path ?? "/");
-		if (permissionError !== void 0) return toolError(runtime, "glob", permissionError);
 		const resolvedBackend = await resolveBackend(backend, runtime);
-		const { pattern, path } = input;
-		const globResult = await resolvedBackend.glob(pattern, path);
+		const { pattern } = input;
+		const permission = await checkPermission(resolvedBackend, permissions, "read", input.path ?? "/");
+		if (permission.error !== void 0) return toolError(runtime, "glob", permission.error);
+		const globResult = await resolvedBackend.glob(pattern, input.path === void 0 ? void 0 : permission.path);
 		if (globResult.error) return `Error finding files: ${globResult.error}`;
-		const infos = filterByPermissions(globResult.files ?? [], permissions, "read", (info) => info.path);
+		const infos = await filterByPermissions(resolvedBackend, globResult.files ?? [], permissions, "read", (info) => info.path);
 		if (infos.length === 0) return `No files found matching pattern '${pattern}'`;
 		const result = truncateIfTooLong(infos.map((info) => info.path));
 		if (Array.isArray(result)) return result.join("\n");
@@ -2516,14 +3090,14 @@ function createGlobTool(backend, options) {
 function createGrepTool(backend, options) {
 	const { customDescription, permissions, includeExecution, grepMaxCount } = options;
 	return (0, langchain.tool)(async (input, runtime) => {
-		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, output_mode = "content" } = input;
+		const permission = await checkPermission(resolvedBackend, permissions, "read", path);
+		if (permission.error !== void 0) return toolError(runtime, "grep", permission.error);
 		const maxCount = input.max_count ?? grepMaxCount;
-		const result = await resolvedBackend.grep(pattern, path, glob, maxCount);
+		const result = await resolvedBackend.grep(pattern, permission.path, glob, maxCount);
 		if (result.error) return result.error;
-		const matches = filterByPermissions(result.matches ?? [], permissions, "read", (m) => m.path);
+		const matches = await filterByPermissions(resolvedBackend, result.matches ?? [], permissions, "read", (m) => m.path);
 		if (matches.length === 0) return `No matches found for pattern '${pattern}'`;
 		const truncated = truncateIfTooLong(formatGrepMatches(matches, output_mode));
 		let content = typeof truncated === "string" ? truncated : truncated.join("\n");
@@ -2587,6 +3161,68 @@ function allPathsScopedToRoutes(permissions, backend) {
 		return path === normalizedRoute.slice(0, -1) || path.startsWith(normalizedRoute);
 	})));
 }
+/** Whether `path` resolves to a `StateBackend`, recursing through composite routing. */
+function routesToStateBackend(backend, path) {
+	if (CompositeBackend.isInstance(backend)) {
+		const [routed, routedPath] = backend.resolveBackendForPath(path);
+		return routesToStateBackend(routed, routedPath);
+	}
+	return StateBackend.isInstance(backend);
+}
+/**
+* Whether `response` is the `{ structuredResponse, messages }` shape a
+* provider-strategy structured-output call can return instead of a plain
+* `AIMessage`. The agent framework only recognizes this shape at the
+* outermost `wrapModelCall` return value — returning a `Command` instead
+* discards `structuredResponse` with no way to carry it through the Command.
+*/
+function hasStructuredResponse(response) {
+	return typeof response === "object" && response !== null && "structuredResponse" in response && "messages" in response;
+}
+const REJECTED_FILE_CONTENT_TEXT = "Unsupported content. The file may be invalid, too large, or of an unsupported mime-type.";
+/**
+* No LangChain error class captures "the provider rejected this request"
+* generically, so this checks the raw HTTP status providers' client SDKs set
+* on their errors instead. `ContextOverflowError` is excluded because it's a
+* different, already-handled problem, and retrying it with stripped file
+* content wouldn't fix an oversized prompt.
+*/
+function isRejectedRequestError(error) {
+	if (_langchain_core_errors.ContextOverflowError.isInstance(error)) return false;
+	return typeof error === "object" && error !== null && "status" in error && error.status === 400;
+}
+/**
+* Only messages carrying multimodal blocks after the last `AIMessage` are
+* candidates for replacement, since anything earlier was already accepted by
+* the model in a prior turn. Returns `messages` unchanged if nothing
+* matched, so the caller can tell there was nothing to blame for the
+* rejection.
+*/
+function replaceRejectedFileContent(messages) {
+	let lastResponseIndex = -1;
+	for (let i = messages.length - 1; i >= 0; i--) if (langchain.AIMessage.isInstance(messages[i])) {
+		lastResponseIndex = i;
+		break;
+	}
+	let changed = false;
+	const result = messages.map((message, index) => {
+		if (index <= lastResponseIndex || !langchain.ToolMessage.isInstance(message) || message.name !== "read_file") return message;
+		if (!message.contentBlocks.some((block) => MULTIMODAL_BLOCK_TYPES.has(block.type))) return message;
+		changed = true;
+		return new langchain.ToolMessage({
+			content: REJECTED_FILE_CONTENT_TEXT,
+			tool_call_id: message.tool_call_id,
+			name: message.name,
+			id: message.id,
+			artifact: message.artifact,
+			status: message.status,
+			metadata: message.metadata,
+			additional_kwargs: message.additional_kwargs,
+			response_metadata: message.response_metadata
+		});
+	});
+	return changed ? result : messages;
+}
 /**
 * Create middleware that provides built-in filesystem tools and optional custom
 * prompt guidance.
@@ -2613,7 +3249,10 @@ function allPathsScopedToRoutes(permissions, backend) {
 * ```
 */
 function createFilesystemMiddleware(options = {}) {
-	const { backend = (runtime) => new StateBackend(runtime), systemPrompt: customSystemPrompt = null, customToolDescriptions = null, toolTokenLimitBeforeEvict = 2e4, humanMessageTokenLimitBeforeEvict = 5e4, permissions = [], tools: filesystemTools = null, grepMaxCount = DEFAULT_GREP_MAX_COUNT } = options;
+	const { backend = (runtime) => new StateBackend(runtime), systemPrompt: customSystemPrompt = null, customToolDescriptions = null, toolTokenLimitBeforeEvict = 2e4, humanMessageTokenLimitBeforeEvict = 5e4, permissions = [], tools: filesystemTools = null, grepMaxCount = DEFAULT_GREP_MAX_COUNT, offloadBinaryContent = false } = options;
+	const backendIsStateBackend = StateBackend.isInstance(backend);
+	if (offloadBinaryContent && backendIsStateBackend) console.warn("offloadBinaryContent has no effect: the backend is a StateBackend, which keeps files as part of checkpointed state.");
+	const blobCache = offloadBinaryContent && !backendIsStateBackend ? new BlobCache() : null;
 	const enabledFilesystemTools = normalizeFilesystemTools(filesystemTools);
 	const executeToolEnabled = enabledFilesystemTools == null || enabledFilesystemTools.has("execute");
 	if (permissions.length > 0) validatePermissionPaths(permissions);
@@ -2750,18 +3389,59 @@ function createFilesystemMiddleware(options = {}) {
 					return msg;
 				});
 			}
-			return handler({
+			let offloadedHuman = [];
+			if (blobCache && !routesToStateBackend(resolvedBackend, `${BLOBS_PREFIX}/`)) {
+				offloadedHuman = await offloadHumanMessages({
+					stateMessages: request.state.messages ?? [],
+					pending: []
+				}, resolvedBackend, BLOBS_PREFIX, blobCache);
+				messages = await hydrateMessages(messages, resolvedBackend, BLOBS_PREFIX, blobCache);
+			}
+			const finalRequest = {
 				...request,
 				tools,
 				messages,
 				systemMessage: newSystemMessage
-			});
+			};
+			const foldOffload = (response, extra = []) => {
+				if (offloadedHuman.length === 0 && extra.length === 0) return response;
+				if (hasStructuredResponse(response)) return {
+					...response,
+					messages: [
+						...extra,
+						...offloadedHuman,
+						...response.messages
+					]
+				};
+				return new _langchain_langgraph.Command({ update: { messages: extra.length === 0 ? offloadedHuman : [
+					...extra,
+					...offloadedHuman,
+					response
+				] } });
+			};
+			try {
+				return foldOffload(await handler(finalRequest));
+			} catch (error) {
+				if (!isRejectedRequestError(error)) throw error;
+				const replaced = replaceRejectedFileContent(finalRequest.messages);
+				if (replaced === finalRequest.messages) throw error;
+				return foldOffload(await handler({
+					...finalRequest,
+					messages: replaced
+				}), replaced.filter((msg, i) => msg !== finalRequest.messages[i]));
+			}
 		},
 		wrapToolCall: async (request, handler) => {
-			if (!toolTokenLimitBeforeEvict) return handler(request);
 			const toolName = request.toolCall?.name;
-			if (toolName && TOOLS_EXCLUDED_FROM_EVICTION.includes(toolName)) return handler(request);
-			const result = await handler(request);
+			let result = await handler(request);
+			if (blobCache && toolName === "read_file") {
+				const resolvedBackend = await resolveBackend(backend, {
+					...request.runtime,
+					state: request.state
+				});
+				if (!routesToStateBackend(resolvedBackend, `${BLOBS_PREFIX}/`)) result = await offloadToolResult(result, resolvedBackend, BLOBS_PREFIX, /* @__PURE__ */ new Map());
+			}
+			if (!toolTokenLimitBeforeEvict || toolName && TOOLS_EXCLUDED_FROM_EVICTION.includes(toolName)) return result;
 			if (langchain.ToolMessage.isInstance(result)) {
 				const processed = await processToolMessage(result, request.runtime, request.state, request.toolCall?.id);
 				if (processed.filesUpdate) return new _langchain_langgraph.Command({ update: {
@@ -3609,10 +4289,12 @@ const EXCLUDED_STATE_KEYS = [
 	"todos",
 	"structuredResponse",
 	"skillsMetadata",
+	"pinnedSkills",
 	"memoryContents",
 	...CALL_COUNT_STATE_KEYS,
 	"_summarizationEvent",
 	"_summarizationSessionId",
+	"_skillToolsDisclosed",
 	FORKED_CONTEXT_KEY
 ];
 /**
@@ -3631,9 +4313,11 @@ const EXCLUDED_STATE_KEYS = [
 */
 const FORK_EXCLUDED_STATE_KEYS = [
 	"structuredResponse",
+	"pinnedSkills",
 	...CALL_COUNT_STATE_KEYS,
 	"_summarizationEvent",
-	"_summarizationSessionId"
+	"_summarizationSessionId",
+	"_skillToolsDisclosed"
 ];
 /**
 * Default description for the general-purpose subagent.
@@ -3805,6 +4489,7 @@ function createSubAgent(spec, options) {
 	if (!spec.tools) throw new Error(`SubAgent '${spec.name}' must specify 'tools'`);
 	const middleware = [...spec.middleware ?? []];
 	if (spec.interruptOn) middleware.push((0, langchain.humanInTheLoopMiddleware)({ interruptOn: spec.interruptOn }));
+	if (!middleware.some((m) => m.name === "UnsupportedContentMiddleware")) middleware.push(createUnsupportedContentMiddleware());
 	const selectedResponseFormat = options?.responseFormat ?? spec.responseFormat;
 	return (0, langchain.createAgent)({
 		model: spec.model,
@@ -4075,7 +4760,8 @@ function patchDanglingToolCalls(messages) {
 				patchedMessages.push(new langchain.ToolMessage({
 					content: toolMsg,
 					name: toolCall.name,
-					tool_call_id: toolCall.id
+					tool_call_id: toolCall.id,
+					status: "error"
 				}));
 			}
 		}
@@ -4517,6 +5203,46 @@ function createMemoryMiddleware(options) {
 	});
 }
 //#endregion
+//#region src/errors.ts
+const CONFIGURATION_ERROR_SYMBOL = Symbol.for("deepagents.configuration_error");
+/**
+* Thrown when `createDeepAgent` receives invalid configuration.
+*
+* Follows the same pattern as {@link SandboxError}: a human-readable
+* `message`, a structured `code` for programmatic handling, and a
+* static `isInstance` guard that works across realms.
+*
+* @example
+* ```typescript
+* try {
+*   createDeepAgent({ tools: [myTool] });
+* } catch (error) {
+*   if (ConfigurationError.isInstance(error)) {
+*     switch (error.code) {
+*       case "TOOL_NAME_COLLISION":
+*         console.error("Rename your tool:", error.message);
+*         break;
+*     }
+*   }
+* }
+* ```
+*/
+var ConfigurationError = class ConfigurationError extends Error {
+	code;
+	cause;
+	[CONFIGURATION_ERROR_SYMBOL] = true;
+	name = "ConfigurationError";
+	constructor(message, code, cause) {
+		super(message);
+		this.code = code;
+		this.cause = cause;
+		Object.setPrototypeOf(this, ConfigurationError.prototype);
+	}
+	static isInstance(error) {
+		return typeof error === "object" && error !== null && error[CONFIGURATION_ERROR_SYMBOL] === true;
+	}
+};
+//#endregion
 //#region src/middleware/skills.ts
 /**
 * Backend-agnostic skills middleware for loading agent skills from any backend.
@@ -4576,6 +5302,10 @@ const SKILL_MODULE_EXTENSIONS = [
 	".jsx",
 	".tsx"
 ];
+/** `SKILL.md` frontmatter `metadata` key listing the skill's include names, space-separated. */
+const INCLUDE_TOOLS_KEY = "include_tools";
+/** YAML frontmatter between `---` delimiters at the start of a `SKILL.md`. */
+const FRONTMATTER_PATTERN = /^---\s*\n([\s\S]*?)\n---\s*\n/;
 /**
 * Zod schema for a single skill metadata entry.
 */
@@ -4617,11 +5347,52 @@ const SkillMetadataEntrySchema = zod.z.object({
 */
 const skillsMetadataValue = zod.z.array(SkillMetadataEntrySchema).nullish();
 /**
+* State value for a middleware's `pinnedSkills` field: the names of skills to
+* pin.
+*
+* The next time the skills middleware's `beforeModel` runs, before a model
+* call, each named skill's `SKILL.md`, without its frontmatter, is appended to
+* the conversation as its own `HumanMessage`, in the order named. The message
+* is a snapshot: editing the file later doesn't change it, and naming the
+* skill again appends a new copy.
+*
+* Names only, matched exactly against the loaded skills. A name that isn't
+* loaded, or whose `SKILL.md` can't be read, is skipped without an error. The
+* key is cleared once consumed, so a later run pins nothing unless it names
+* skills again. Writes in the same step add up, so parallel tool calls can
+* each pin skills by returning a `Command`.
+*
+* Like {@link skillsMetadataValue}, treat the value as opaque. A middleware
+* declares it on its state schema to set `pinnedSkills` from its own hooks.
+*
+* @example
+* ```typescript
+* import { createMiddleware } from "langchain";
+* import { StateSchema } from "@langchain/langgraph";
+* import { pinnedSkillsValue } from "deepagents";
+*
+* const routeSkills = createMiddleware({
+*   name: "RouteSkills",
+*   stateSchema: new StateSchema({ pinnedSkills: pinnedSkillsValue }),
+*   beforeAgent: (state) => ({ pinnedSkills: skillsFor(state.messages) }),
+* });
+* ```
+*/
+const pinnedSkillsValue = new _langchain_langgraph.ReducedValue(zod.z.array(zod.z.string()).default(() => []), { reducer: (stored, written) => [...stored ?? [], ...written ?? []] });
+/**
 * State schema for skills middleware.
 */
 const SkillsStateSchema = new _langchain_langgraph.StateSchema({
 	skillsMetadata: skillsMetadataValue,
-	files: filesValue
+	pinnedSkills: pinnedSkillsValue,
+	files: filesValue,
+	/**
+	* The skill tools disclosed to the latest model call, each mapped to the
+	* include name that produced it, for the tool-time gate. Written on every
+	* model call of a skills middleware with skill tools. The last write wins,
+	* so a model call retried within one step can write it again.
+	*/
+	_skillToolsDisclosed: new _langchain_langgraph.ReducedValue(zod.z.record(zod.z.string(), zod.z.string()).optional(), { reducer: (_previous, next) => next })
 });
 /**
 * Skills System Documentation prompt template.
@@ -4723,7 +5494,8 @@ function validateSkillName(name, directoryName) {
 *
 * YAML parsing can return any type for the `metadata` key. This ensures the
 * value in {@link SkillMetadata} is always a `Record<string, string>` by
-* coercing via `String()` and rejecting non-object inputs.
+* coercing via `String()` and rejecting non-object inputs. It also warns when
+* `include_tools` isn't a space-separated string of tool names.
 *
 * @param raw - Raw value from `frontmatterData.metadata`.
 * @param skillPath - Path to the `SKILL.md` file (for warning messages).
@@ -4734,6 +5506,8 @@ function validateMetadata(raw, skillPath) {
 		if (raw) console.warn(`Ignoring non-object metadata in ${skillPath} (got ${typeof raw})`);
 		return {};
 	}
+	const includeTools = raw[INCLUDE_TOOLS_KEY];
+	if (Array.isArray(includeTools) || typeof includeTools === "string" && includeTools.includes(",")) console.warn(`metadata.include_tools in ${skillPath} should be a space-separated string of tool names; got ${JSON.stringify(includeTools)}`);
 	const result = {};
 	for (const [k, v] of Object.entries(raw)) result[String(k)] = String(v);
 	return result;
@@ -4771,7 +5545,7 @@ function parseSkillMetadataFromContent(content, skillPath, directoryName) {
 		console.warn(`Skipping ${skillPath}: content too large (${content.length} bytes)`);
 		return null;
 	}
-	const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+	const match = content.match(FRONTMATTER_PATTERN);
 	if (!match) {
 		console.warn(`Skipping ${skillPath}: no valid YAML frontmatter found`);
 		return null;
@@ -4890,6 +5664,61 @@ async function listSkillsFromBackend(backend, sourcePath) {
 	return skills;
 }
 /**
+* Load the skills in every source, in order. A later source's skill replaces
+* an earlier one of the same name.
+*/
+async function loadSkills(backend, sources) {
+	const allSkills = /* @__PURE__ */ new Map();
+	for (const sourcePath of sources) try {
+		const skills = await listSkillsFromBackend(backend, sourcePath);
+		for (const skill of skills) allSkills.set(skill.name, skill);
+	} catch (error) {
+		console.debug(`[BackendSkillsMiddleware] Failed to load skills from ${sourcePath}:`, error);
+	}
+	return Array.from(allSkills.values());
+}
+/**
+* Return a message pinning each skill `names` refers to, in first-seen order.
+*
+* Skips a name that isn't in `skills`, and a skill whose `SKILL.md` is
+* missing, unreadable, empty, or larger than {@link MAX_SKILL_FILE_SIZE}.
+*/
+async function buildPinnedSkillMessages(backend, names, skills) {
+	const adaptedBackend = adaptBackendProtocol(backend);
+	const skillsByName = new Map(skills.map((skill) => [skill.name, skill]));
+	const skillsToPin = [...new Set(names)].flatMap((name) => {
+		const skill = skillsByName.get(name);
+		return skill === void 0 ? [] : [skill];
+	});
+	const contents = await Promise.all(skillsToPin.map((skill) => readFileFromBackend(adaptedBackend, skill.path).catch(() => null)));
+	return skillsToPin.flatMap((skill, i) => {
+		const content = contents[i];
+		if (!content || content.length > 10485760) return [];
+		return [buildPinnedSkillMessage(skill, content)];
+	});
+}
+/** Return the message pinning `skill`, carrying its `SKILL.md` `content` without frontmatter. */
+function buildPinnedSkillMessage(skill, content) {
+	const body = content.replace(FRONTMATTER_PATTERN, "").trimEnd();
+	const name = escapeXmlAttribute(skill.name);
+	const path = escapeXmlAttribute(skill.path);
+	return new _langchain_core_messages.HumanMessage({
+		content: `<skill name="${name}" path="${path}">\n${body}\n</skill>`,
+		additional_kwargs: {
+			lc_source: "pinned_skill",
+			skill: {
+				name: skill.name,
+				path: skill.path,
+				description: skill.description
+			}
+		}
+	});
+}
+/** Escape `value` for a double-quoted XML attribute. */
+function escapeXmlAttribute(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+/**
 * Format skills locations for display in system prompt.
 * Shows priority indicator for the last source (highest priority).
 */
@@ -4949,6 +5778,336 @@ function validateModulePath(raw) {
 	if (!endsWithModuleExtension(normalized)) return;
 	return normalized;
 }
+/** Tool `extras` key (and provider field) that withholds a tool's schema until searched for. */
+const DEFER_LOADING = "defer_loading";
+/**
+* Model ID prefixes that accept an inline `tool_definition` mid-conversation.
+*
+* `@langchain/anthropic` sends any mid-conversation system message in place,
+* without gating on the model, so this list is the only guard.
+*/
+const ANTHROPIC_INLINE_TOOL_MODELS = [
+	"claude-opus-5",
+	"claude-fable-5",
+	"claude-mythos-5",
+	"claude-opus-4-8"
+];
+/** Models whose Responses API accepts an `additional_tools` input item, matched with or without a `-` suffix such as a snapshot date. */
+const OPENAI_INLINE_TOOL_MODELS = ["gpt-6", "gpt-5.6"];
+/** Root `input_schema` keys the Anthropic API rejects, failing the whole request. */
+const ANTHROPIC_ROOT_COMBINATORS = [
+	"oneOf",
+	"anyOf",
+	"allOf"
+];
+/** `extras` keys `ChatAnthropic` copies into a tool's definition, bar the ones a disclosure must never carry. */
+const ANTHROPIC_DEFINITION_EXTRAS = [
+	"input_examples",
+	"allowed_callers",
+	"strict"
+];
+/**
+* Return the resolver the skills middleware's `tools` option stands for.
+*
+* A list is validated, then resolved by exact name.
+*
+* @throws {ConfigurationError} If `tools` is neither a list nor a function,
+*   or a list entry isn't a client tool or repeats a name.
+*/
+function toSkillToolResolver(tools) {
+	if (tools != null && !Array.isArray(tools)) {
+		if (typeof tools !== "function") throw new ConfigurationError(`tools must be an array of tools or a resolver function, got ${typeof tools}; wrap a single tool in an array`, "SKILL_TOOLS_UNSUPPORTED_TYPE");
+		return tools;
+	}
+	const entries = tools ?? [];
+	if (!entries.every(isClientTool)) throw new ConfigurationError("tools entries must be client tools; provider-native tool objects are not supported", "SKILL_TOOLS_UNSUPPORTED_TYPE");
+	const names = entries.map((t) => t.name);
+	const duplicates = [...new Set(names.filter((n, i) => names.indexOf(n) !== i))].sort();
+	if (duplicates.length > 0) throw new ConfigurationError(`tools contains duplicate tool name(s): ${duplicates.join(", ")}`, "SKILL_TOOLS_DUPLICATE_NAME");
+	const byName = new Map(entries.map((t) => [t.name, t]));
+	return (name) => byName.has(name) ? [byName.get(name)] : [];
+}
+/** Whether `value` is a runnable client tool rather than a provider-native or plain object. */
+function isClientTool(value) {
+	return _langchain_core_runnables.Runnable.isRunnable(value) && typeof value.name === "string";
+}
+/**
+* Call `resolver` for one include name, keeping the first of each tool name.
+*
+* @throws {TypeError} If the resolver returns something other than an array
+*   of client tools.
+*/
+async function callSkillToolResolver(resolver, includeName, runtime) {
+	const result = await resolver(includeName, runtime);
+	if (!Array.isArray(result)) throw new TypeError(`skill tool resolver must return an array of tools for '${includeName}', got ${typeof result}`);
+	const tools = /* @__PURE__ */ new Map();
+	for (const item of result) {
+		if (!isClientTool(item)) throw new TypeError(`skill tool resolver returned a non-tool ${typeof item} for '${includeName}'; expected tool instances`);
+		if (!tools.has(item.name)) tools.set(item.name, item);
+	}
+	return [...tools.values()];
+}
+/**
+* Return every successful `read_file` or pin of a `SKILL.md` that lists
+* tools, in message order.
+*
+* The read's or pin's path must equal the skill's path exactly, as the skills
+* listing shows it. Any `offset` or `limit` counts, and so does a result whose
+* content was later truncated or compacted, since only the call and the
+* result's status are read.
+*/
+function findSkillReads(messages, skills) {
+	const skillsByPath = /* @__PURE__ */ new Map();
+	for (const skill of skills) {
+		const value = skill.metadata?.[INCLUDE_TOOLS_KEY];
+		const includeNames = typeof value === "string" ? value.split(/\s+/).filter(Boolean) : [];
+		if (includeNames.length > 0) skillsByPath.set(skill.path, { includeNames });
+	}
+	if (skillsByPath.size === 0) return [];
+	const readPaths = /* @__PURE__ */ new Map();
+	for (const message of messages) {
+		if (!_langchain_core_messages.AIMessage.isInstance(message)) continue;
+		for (const toolCall of message.tool_calls ?? []) if (toolCall.name === "read_file" && toolCall.id) readPaths.set(toolCall.id, toolCall.args?.file_path ?? toolCall.args?.path);
+	}
+	const reads = [];
+	messages.forEach((message, index) => {
+		let path;
+		if (_langchain_core_messages.ToolMessage.isInstance(message) && message.status !== "error") path = readPaths.get(message.tool_call_id);
+		else if (_langchain_core_messages.HumanMessage.isInstance(message) && message.additional_kwargs?.lc_source === "pinned_skill") path = message.additional_kwargs.skill?.path;
+		else return;
+		const skill = typeof path === "string" ? skillsByPath.get(path) : void 0;
+		if (skill !== void 0) reads.push({
+			index,
+			...skill
+		});
+	});
+	return reads;
+}
+/** Return a request tool's name, whether it is a tool instance or a provider object. */
+function toolName(tool) {
+	if ((0, _langchain_core_language_models_base.isOpenAITool)(tool)) return tool.function.name;
+	return typeof tool.name === "string" ? tool.name : void 0;
+}
+/**
+* Disclose the tools the read skills' include names produce to one model call.
+*
+* Returns the request to send, and the record of the skill tools it
+* discloses, for the tool-time gate.
+*/
+async function discloseSkillTools(request, reads, resolver) {
+	const requestTools = /* @__PURE__ */ new Map();
+	for (const tool of request.tools) {
+		const name = toolName(tool);
+		if (name !== void 0) requestTools.set(name, tool);
+	}
+	const names = [...new Set(reads.flatMap((read) => read.includeNames.filter((name) => !requestTools.has(name))))];
+	const tools = await Promise.all(names.map((name) => callSkillToolResolver(resolver, name, request.runtime)));
+	const disclosed = planDisclosure(reads, requestTools, new Map(names.map((name, i) => [name, tools[i]])));
+	if (disclosed.size === 0) return {
+		request,
+		record: {}
+	};
+	const chatModel = await resolveChatModel(request.model, request.runtime);
+	if (llmType(chatModel) === "anthropic") withholdRootCombinatorTools(disclosed);
+	const gatedNames = [...disclosed.keys()].filter((name) => disclosed.get(name).includeName !== void 0).sort();
+	const record = Object.fromEntries(gatedNames.map((name) => [name, disclosed.get(name).includeName]));
+	if (disclosed.size === 0) return {
+		request,
+		record
+	};
+	const build = inlineBlockBuilder(chatModel);
+	if (build !== void 0) return {
+		request: {
+			...request,
+			messages: discloseInMessages(request.messages, disclosed, build)
+		},
+		record
+	};
+	return {
+		request: {
+			...request,
+			tools: discloseInTools(request.tools, disclosed, gatedNames)
+		},
+		record
+	};
+}
+/**
+* Classify what each read skill's include names produce, anchoring each tool
+* at the earliest read producing it.
+*
+* An include name that matches a request tool's name produces that tool; any
+* other produces what the resolver returned for it. A produced tool whose name
+* a request tool has wins as that request tool, because it's the one that
+* runs: a deferred one is disclosed early, and a bound one adds nothing, since
+* the model already sees it. Tools are matched by name, never by identity,
+* because outer middleware such as tool search replaces the request's tools
+* with copies.
+*/
+function planDisclosure(reads, requestTools, resolved) {
+	const disclosed = /* @__PURE__ */ new Map();
+	const discloseIfDeferred = (name, anchor) => {
+		const entry = requestTools.get(name);
+		if (!disclosed.has(name) && (0, _langchain_core_tools.isLangChainTool)(entry) && entry.extras?.[DEFER_LOADING] === true) disclosed.set(name, {
+			tool: entry,
+			anchor
+		});
+	};
+	for (const { index, includeNames } of reads) for (const includeName of includeNames) {
+		if (requestTools.has(includeName)) {
+			discloseIfDeferred(includeName, index);
+			continue;
+		}
+		for (const tool of resolved.get(includeName) ?? []) {
+			if (disclosed.has(tool.name)) continue;
+			if (requestTools.has(tool.name)) discloseIfDeferred(tool.name, index);
+			else disclosed.set(tool.name, {
+				tool,
+				anchor: index,
+				includeName
+			});
+		}
+	}
+	return disclosed;
+}
+/**
+* Withhold each disclosed tool whose root input schema uses `oneOf`, `anyOf`
+* or `allOf`, which the Anthropic API rejects, failing the whole request, in
+* `tools` and inline alike. Withholding it on every path keeps the record
+* equal to what the model was shown.
+*/
+function withholdRootCombinatorTools(disclosed) {
+	for (const [name, { tool }] of disclosed) {
+		const schema = anthropicDefinition(tool).input_schema;
+		const keys = ANTHROPIC_ROOT_COMBINATORS.filter((key) => typeof schema === "object" && schema !== null && Object.prototype.hasOwnProperty.call(schema, key));
+		if (keys.length > 0) {
+			console.warn(`Not disclosing tool '${name}': its input_schema has a top-level ${keys.join("/")}, which the Anthropic API does not support`);
+			disclosed.delete(name);
+		}
+	}
+}
+/**
+* Insert one `SystemMessage` per insertion point, carrying the tools anchored
+* there, for models that accept tool definitions mid-conversation.
+*
+* Each message lands at the same index with the same bytes on every call while
+* its anchor stays visible, so the provider's cached prefix survives.
+*/
+function discloseInMessages(messages, disclosed, build) {
+	const namesByIndex = /* @__PURE__ */ new Map();
+	for (const [name, { anchor }] of disclosed) {
+		let index = anchor + 1;
+		while (index < messages.length) {
+			const message = messages[index];
+			const emptyReply = _langchain_core_messages.AIMessage.isInstance(message) && message.content.length === 0 && !message.tool_calls?.length;
+			if (!_langchain_core_messages.ToolMessage.isInstance(message) && !_langchain_core_messages.HumanMessage.isInstance(message) && !emptyReply) break;
+			index += 1;
+		}
+		namesByIndex.set(index, [...namesByIndex.get(index) ?? [], name]);
+	}
+	const result = [...messages];
+	for (const index of [...namesByIndex.keys()].sort((a, b) => b - a)) {
+		const blocks = namesByIndex.get(index).sort().map((name) => build(disclosed.get(name).tool));
+		result.splice(index, 0, new _langchain_core_messages.SystemMessage({ content: blocks }));
+	}
+	return result;
+}
+/**
+* Return `requestTools` with deferred disclosures undeferred and skill tools
+* appended, for models that can't take tool definitions mid-conversation.
+*
+* A deferred tool is replaced by a plain spec rather than a copy: `createAgent`
+* rejects a request that swaps a registered tool for another instance of the
+* same name, and doesn't validate plain objects.
+*/
+function discloseInTools(requestTools, disclosed, gatedNames) {
+	return [...requestTools.map((tool) => {
+		const name = toolName(tool);
+		const entry = name === void 0 ? void 0 : disclosed.get(name);
+		if (entry?.tool !== tool || entry.includeName !== void 0) return tool;
+		const { description, schema, extras = {} } = entry.tool;
+		const { [DEFER_LOADING]: _deferLoading, ...rest } = extras;
+		return {
+			name,
+			description,
+			schema,
+			extras: rest
+		};
+	}), ...gatedNames.map((name) => disclosed.get(name).tool)];
+}
+/** Return the model inside a `bind()` / `withConfig()` wrapper; chained calls merge into one. */
+function unwrapBinding(model) {
+	return _langchain_core_runnables.RunnableBinding.isRunnableBinding(model) ? model.bound : model;
+}
+/**
+* Return the concrete chat model a request will call.
+*
+* Resolves a `ConfigurableModel`, which a string `model` always becomes, to
+* the instance it will call with this run's `configurable`. Without
+* configurable overrides that's the instance cached at creation: the instance
+* cache is keyed on the whole config, so passing `configurable`
+* unconditionally would build one per thread.
+*/
+async function resolveChatModel(model, runtime) {
+	const current = unwrapBinding(model);
+	if (current?._queuedMethodOperations === void 0 || typeof current._getModelInstance !== "function") return current;
+	const configurable = runtime.configurable ?? {};
+	const overrides = current._modelParams?.({ configurable }) ?? {};
+	return unwrapBinding(Object.keys(overrides).length > 0 ? await current._getModelInstance({ configurable }) : await current._getModelInstance());
+}
+/** Return a chat model's `_llmType()`, which tells providers apart. */
+function llmType(model) {
+	const fn = model?._llmType;
+	return typeof fn === "function" ? fn.call(model) : void 0;
+}
+/**
+* Return how `chatModel` is given a tool mid-conversation, or `undefined` if
+* it can't be.
+*
+* The one place that decides support, so a model-profile capability can
+* replace the allowlists later.
+*/
+function inlineBlockBuilder(chatModel) {
+	const { model: name, useResponsesApi } = chatModel;
+	if (typeof name !== "string") return void 0;
+	const type = llmType(chatModel);
+	if (type === "anthropic" && ANTHROPIC_INLINE_TOOL_MODELS.some((prefix) => name.startsWith(prefix))) return anthropicToolAddition;
+	if (type === "openai" && useResponsesApi === true && OPENAI_INLINE_TOOL_MODELS.some((model) => name === model || name.startsWith(`${model}-`))) return openaiAdditionalTools;
+}
+/**
+* Return the definition `ChatAnthropic` sends in `tools` for `tool`, without
+* `defer_loading` (a deferred definition would stay withheld) or
+* `cache_control` (a stray marker uses up a breakpoint).
+*/
+function anthropicDefinition(tool) {
+	const definition = {
+		name: tool.name,
+		description: tool.description,
+		input_schema: (0, _langchain_core_utils_types.isInteropZodSchema)(tool.schema) ? (0, _langchain_core_utils_json_schema.toJsonSchema)(tool.schema) : tool.schema
+	};
+	for (const key of ANTHROPIC_DEFINITION_EXTRAS) if (tool.extras?.[key] !== void 0) definition[key] = tool.extras[key];
+	return definition;
+}
+/** Build the Anthropic `tool_addition` block carrying `tool`'s full definition. */
+function anthropicToolAddition(tool) {
+	return {
+		type: "tool_addition",
+		tool: {
+			type: "tool_definition",
+			definition: anthropicDefinition(tool)
+		}
+	};
+}
+/** Build the OpenAI Responses `additional_tools` item carrying `tool`'s function schema. */
+function openaiAdditionalTools(tool) {
+	return {
+		type: "additional_tools",
+		role: "developer",
+		tools: [{
+			type: "function",
+			...(0, _langchain_core_utils_function_calling.convertToOpenAIFunction)(tool)
+		}]
+	};
+}
 /**
 * Create backend-agnostic middleware for loading and exposing agent skills.
 *
@@ -4972,8 +6131,62 @@ function validateModulePath(raw) {
 * invalidate from any hook — including mid-run, from `afterModel` — and see
 * the fresh list on the following call. See {@link skillsMetadataValue}.
 *
+* To guarantee the model gets a skill's instructions, for example when the
+* user names it, pass its name in `pinnedSkills`. Before the next model call,
+* each named skill's `SKILL.md`, without its frontmatter, is appended to the
+* conversation as its own `HumanMessage`, with `additional_kwargs.lc_source`
+* set to `"pinned_skill"` and the skill's `name`, `path` and `description`
+* under `additional_kwargs.skill`:
+*
+* ```ts
+* await agent.invoke(
+*   {
+*     messages: [new HumanMessage("/write-tests /house-style for auth.py")],
+*     pinnedSkills: ["write-tests", "house-style"],
+*   },
+*   config,
+* );
+* ```
+*
+* Pins resolve against the skills loaded for the thread, so reset
+* `skillsMetadata` in the same input to pin a skill added since. See
+* {@link pinnedSkillsValue}.
+*
+* ## Skill tools
+*
+* A skill can list the tools its instructions use, separated by spaces, under
+* `metadata.include_tools` in its `SKILL.md` frontmatter:
+*
+* ```yaml
+* metadata:
+*   include_tools: create_customer_request list_customer_requests
+* ```
+*
+* Pass those tools as `tools`, either as an array or as a
+* {@link SkillToolResolver} that looks them up by name when a skill is read
+* or pinned, so one name can stand for a family of tools whose real names are
+* only known at runtime. The model sees a skill tool only after it reads, with
+* `read_file`, a skill that lists it, or the skill is pinned, and only while
+* that read or pin stays in the conversation it is sent; compaction that drops
+* the read or pin withdraws the tool.
+* Until then, calling the tool fails with the standard invalid-tool error and
+* the tool doesn't run. This controls what is in the model's context; it is
+* not a security boundary, since the model can read any `SKILL.md` at any
+* time.
+*
+* `include_tools` can also name a tool passed to the agent rather than to this
+* middleware. That tool wins over a skill tool of the same name. If it is
+* deferred (`extras: { defer_loading: true }`), reading or pinning the skill
+* discloses it early, and it stays deferred and searchable; if it is bound,
+* nothing changes.
+*
+*
 * @param options - Configuration options
 * @returns AgentMiddleware for skills loading and injection
+* @throws {ConfigurationError} If `tools` is neither an array nor a
+*   function (`SKILL_TOOLS_UNSUPPORTED_TYPE`), an entry isn't a client tool
+*   (`SKILL_TOOLS_UNSUPPORTED_TYPE`), or two entries share a name
+*   (`SKILL_TOOLS_DUPLICATE_NAME`).
 *
 * @example
 * ```typescript
@@ -4985,30 +6198,60 @@ function validateModulePath(raw) {
 */
 function createSkillsMiddleware(options) {
 	const { backend, sources } = options;
+	const skillToolResolver = toSkillToolResolver(options.tools);
+	const hasSkillTools = typeof options.tools === "function" || Array.isArray(options.tools) && options.tools.length > 0;
 	return (0, langchain.createMiddleware)({
 		name: "SkillsMiddleware",
 		stateSchema: SkillsStateSchema,
 		async beforeModel(state) {
-			if (state.skillsMetadata !== null && state.skillsMetadata !== void 0) return;
+			const needsLoad = state.skillsMetadata === null || state.skillsMetadata === void 0;
+			const pinnedNames = state.pinnedSkills ?? [];
+			if (!needsLoad && pinnedNames.length === 0) return;
 			const resolvedBackend = await resolveBackend(backend, { state });
-			const allSkills = /* @__PURE__ */ new Map();
-			for (const sourcePath of sources) try {
-				const skills = await listSkillsFromBackend(resolvedBackend, sourcePath);
-				for (const skill of skills) allSkills.set(skill.name, skill);
-			} catch (error) {
-				console.debug(`[BackendSkillsMiddleware] Failed to load skills from ${sourcePath}:`, error);
-			}
-			return { skillsMetadata: Array.from(allSkills.values()) };
+			const skillsMetadata = state.skillsMetadata ?? await loadSkills(resolvedBackend, sources);
+			if (pinnedNames.length === 0) return { skillsMetadata };
+			const messages = await buildPinnedSkillMessages(resolvedBackend, pinnedNames, skillsMetadata);
+			return {
+				...needsLoad && { skillsMetadata },
+				...messages.length > 0 && { messages },
+				pinnedSkills: new _langchain_langgraph.Overwrite([])
+			};
 		},
-		wrapModelCall(request, handler) {
+		async wrapModelCall(request, handler) {
 			const skillsMetadata = request.state?.skillsMetadata || [];
 			const skillsLocations = formatSkillsLocations(sources);
 			const skillsList = formatSkillsList(skillsMetadata, sources);
 			const skillsSection = SKILLS_SYSTEM_PROMPT.replace("{skills_locations}", skillsLocations).replace("{skills_list}", skillsList);
 			const newSystemMessage = request.systemMessage.concat(skillsSection);
-			return handler({
+			const prompted = {
 				...request,
 				systemMessage: newSystemMessage
+			};
+			const reads = findSkillReads(request.messages, skillsMetadata);
+			const { request: disclosed, record } = reads.length === 0 ? {
+				request: prompted,
+				record: {}
+			} : await discloseSkillTools(prompted, reads, skillToolResolver);
+			const response = await handler(disclosed);
+			const stored = request.state._skillToolsDisclosed;
+			if (!hasSkillTools && Object.keys(stored ?? {}).length === 0) return response;
+			if (typeof response === "object" && response !== null && "structuredResponse" in response) return response;
+			return new _langchain_langgraph.Command({ update: { _skillToolsDisclosed: record } });
+		},
+		async wrapToolCall(request, handler) {
+			if (request.tool !== void 0) return handler(request);
+			const name = request.toolCall.name;
+			const record = request.state._skillToolsDisclosed ?? {};
+			const includeName = Object.hasOwn(record, name) ? record[name] : void 0;
+			if (includeName === void 0) return handler(request);
+			const tool = (await callSkillToolResolver(skillToolResolver, includeName, request.runtime)).find((candidate) => candidate.name === name);
+			if (tool === void 0) {
+				console.warn(`Skill tool '${name}' was disclosed via '${includeName}', but the resolver no longer returns it`);
+				return handler(request);
+			}
+			return handler({
+				...request,
+				tool
 			});
 		}
 	});
@@ -5778,46 +7021,6 @@ function createAsyncSubAgentMiddleware(options) {
 	});
 }
 //#endregion
-//#region src/errors.ts
-const CONFIGURATION_ERROR_SYMBOL = Symbol.for("deepagents.configuration_error");
-/**
-* Thrown when `createDeepAgent` receives invalid configuration.
-*
-* Follows the same pattern as {@link SandboxError}: a human-readable
-* `message`, a structured `code` for programmatic handling, and a
-* static `isInstance` guard that works across realms.
-*
-* @example
-* ```typescript
-* try {
-*   createDeepAgent({ tools: [myTool] });
-* } catch (error) {
-*   if (ConfigurationError.isInstance(error)) {
-*     switch (error.code) {
-*       case "TOOL_NAME_COLLISION":
-*         console.error("Rename your tool:", error.message);
-*         break;
-*     }
-*   }
-* }
-* ```
-*/
-var ConfigurationError = class ConfigurationError extends Error {
-	code;
-	cause;
-	[CONFIGURATION_ERROR_SYMBOL] = true;
-	name = "ConfigurationError";
-	constructor(message, code, cause) {
-		super(message);
-		this.code = code;
-		this.cause = cause;
-		Object.setPrototypeOf(this, ConfigurationError.prototype);
-	}
-	static isInstance(error) {
-		return typeof error === "object" && error !== null && error[CONFIGURATION_ERROR_SYMBOL] === true;
-	}
-};
-//#endregion
 //#region src/middleware/cache.ts
 /**
 * Creates a middleware that places a cache breakpoint at the end of the static
@@ -6683,13 +7886,10 @@ function createDeepAgent(params = {}) {
 		harnessProfile.systemPromptSuffix
 	]);
 	/**
-	* Process subagents to add SkillsMiddleware for those with their own skills.
-	*
-	* Custom subagents do NOT inherit skills from the main agent by default.
-	* Only the general-purpose subagent inherits the main agent's skills.
-	* If a custom subagent needs skills, it must specify its own `skills` array.
+	* Build the default head of a declarative subagent's middleware stack.
+	* Skills go in the tail instead (see buildSubagentMiddleware).
 	*/
-	const createSubagentDefaultMiddleware = (input, subagentProfile, forked) => {
+	const createSubagentDefaultMiddleware = (input, subagentProfile) => {
 		const effectivePermissions = input.permissions ?? permissions;
 		return [
 			createFilesystemMiddleware({
@@ -6698,23 +7898,33 @@ function createDeepAgent(params = {}) {
 				tools: computeProfileFilesystemTools(subagentProfile)
 			}),
 			createSummarizationMiddleware({ backend }),
-			createPatchToolCallsMiddleware(),
-			...!forked && input.skills != null && input.skills.length > 0 ? [createSkillsMiddleware({
-				backend,
-				sources: input.skills
-			})] : []
+			createPatchToolCallsMiddleware()
 		];
 	};
-	const buildSubagentMiddleware = (input) => {
+	/**
+	* The skills middleware for a stack: the last `SkillsMiddleware` among its
+	* custom middleware, else one built from `sources`, else none. A custom one
+	* is picked here rather than left to replace the default by name, because
+	* without `sources` there is no default to replace and it would run with
+	* the novel middleware instead.
+	*/
+	const resolveSkillsMiddleware = (sources, custom) => {
+		const passed = custom.findLast((entry) => entry.name === "SkillsMiddleware");
+		if (passed !== void 0) return [passed];
+		return sources != null && sources.length > 0 ? [createSkillsMiddleware({
+			backend,
+			sources
+		})] : [];
+	};
+	const buildSubagentMiddleware = (input, generalPurpose = false) => {
 		const subagentProfile = resolveSubagentProfile(input.model);
 		const forked = isForkedSubAgent(input);
-		const subagentDefaultMiddleware = createSubagentDefaultMiddleware(input, subagentProfile, forked);
-		if (forked && skills != null && skills.length > 0) subagentDefaultMiddleware.unshift(createSkillsMiddleware({
-			backend,
-			sources: skills
-		}));
-		let subagentMiddleware = mergeMiddlewareStack(subagentDefaultMiddleware, forked && customMiddleware.length > 0 ? mergeMiddleware$1(customMiddleware, input.middleware ?? []) : input.middleware ?? [], [
+		const subagentDefaultMiddleware = createSubagentDefaultMiddleware(input, subagentProfile);
+		const inputMiddleware = forked && customMiddleware.length > 0 ? mergeMiddleware$1(customMiddleware, input.middleware ?? []) : input.middleware ?? [];
+		const subagentSkillsMiddleware = generalPurpose ? resolveSkillsMiddleware(skills, customMiddleware) : resolveSkillsMiddleware(forked ? skills : input.skills, inputMiddleware);
+		let subagentMiddleware = mergeMiddlewareStack(subagentDefaultMiddleware, inputMiddleware, [
 			...resolveMiddleware(subagentProfile.extraMiddleware),
+			...subagentSkillsMiddleware,
 			...cacheMiddleware,
 			...forked && memory != null && memory.length > 0 ? [createMemoryMiddleware({
 				backend,
@@ -6724,11 +7934,12 @@ function createDeepAgent(params = {}) {
 		]);
 		if (subagentProfile.excludedMiddleware.size > 0) subagentMiddleware = subagentMiddleware.filter((middleware) => !subagentProfile.excludedMiddleware.has(middleware.name));
 		if (subagentProfile.excludedTools.size > 0) subagentMiddleware.push(createToolExclusionMiddleware(subagentProfile.excludedTools));
+		if (!subagentProfile.excludedMiddleware.has("UnsupportedContentMiddleware") && !subagentMiddleware.some((middleware) => middleware.name === "UnsupportedContentMiddleware")) subagentMiddleware.push(createUnsupportedContentMiddleware());
 		return subagentMiddleware;
 	};
-	const normalizeSubagentSpec = (input) => ({
+	const normalizeSubagentSpec = (input, generalPurpose = false) => ({
 		...input,
-		middleware: buildSubagentMiddleware(input)
+		middleware: buildSubagentMiddleware(input, generalPurpose)
 	});
 	const allSubagents = subagents;
 	const asyncSubAgents = allSubagents.filter((item) => isAsyncSubAgent(item));
@@ -6741,16 +7952,12 @@ function createDeepAgent(params = {}) {
 			description: gpConfig?.description ?? GENERAL_PURPOSE_SUBAGENT.description,
 			systemPrompt: gpSystemPrompt,
 			model,
-			skills,
 			tools: effectiveTools
-		});
+		}, true);
 		generalPurposeSpec.middleware = mergeMiddlewareStack(generalPurposeSpec.middleware ?? [], customMiddleware, [], { appendNew: false });
 		inlineSubagents.unshift(generalPurposeSpec);
 	}
-	const skillsMiddleware = skills != null && skills.length > 0 ? [createSkillsMiddleware({
-		backend,
-		sources: skills
-	})] : [];
+	const skillsMiddleware = resolveSkillsMiddleware(skills, customMiddleware);
 	const [fsMiddleware, subagentMiddleware, summarizationMiddleware, patchToolCallsMiddleware] = [
 		createFilesystemMiddleware({
 			backend,
@@ -6769,7 +7976,6 @@ function createDeepAgent(params = {}) {
 		createPatchToolCallsMiddleware()
 	];
 	let middleware = mergeMiddlewareStack([
-		...skillsMiddleware,
 		fsMiddleware,
 		subagentMiddleware,
 		summarizationMiddleware,
@@ -6777,6 +7983,7 @@ function createDeepAgent(params = {}) {
 		...asyncSubAgents.length > 0 ? [createAsyncSubAgentMiddleware({ asyncSubAgents })] : []
 	], customMiddleware, [
 		...resolveMiddleware(harnessProfile.extraMiddleware),
+		...skillsMiddleware,
 		...cacheMiddleware,
 		...memoryMiddleware,
 		...interruptOn ? [(0, langchain.humanInTheLoopMiddleware)({ interruptOn })] : []
@@ -6786,6 +7993,7 @@ function createDeepAgent(params = {}) {
 		middleware = middleware.filter((entry) => !excluded.has(entry.name));
 	}
 	if (harnessProfile.excludedTools.size > 0) middleware.push(createToolExclusionMiddleware(harnessProfile.excludedTools));
+	if (!harnessProfile.excludedMiddleware.has("UnsupportedContentMiddleware") && !middleware.some((m) => m.name === "UnsupportedContentMiddleware")) middleware.push(createUnsupportedContentMiddleware());
 	/**
 	* Return as DeepAgent with proper DeepAgentTypeConfig
 	* - Response: InferStructuredResponse<TResponse> (unwraps ToolStrategy<T>/ProviderStrategy<T> → T)
@@ -8993,6 +10201,12 @@ Object.defineProperty(exports, "MAX_SKILL_NAME_LENGTH", {
 		return MAX_SKILL_NAME_LENGTH;
 	}
 });
+Object.defineProperty(exports, "MULTIMODAL_BLOCK_TYPES", {
+	enumerable: true,
+	get: function() {
+		return MULTIMODAL_BLOCK_TYPES;
+	}
+});
 Object.defineProperty(exports, "REQUIRED_MIDDLEWARE_NAMES", {
 	enumerable: true,
 	get: function() {
@@ -9131,6 +10345,12 @@ Object.defineProperty(exports, "createSummarizationMiddleware", {
 		return createSummarizationMiddleware;
 	}
 });
+Object.defineProperty(exports, "createUnsupportedContentMiddleware", {
+	enumerable: true,
+	get: function() {
+		return createUnsupportedContentMiddleware;
+	}
+});
 Object.defineProperty(exports, "filesValue", {
 	enumerable: true,
 	get: function() {
@@ -9185,6 +10405,12 @@ Object.defineProperty(exports, "isTextMimeType", {
 		return isTextMimeType;
 	}
 });
+Object.defineProperty(exports, "multimodalBlockSupported", {
+	enumerable: true,
+	get: function() {
+		return multimodalBlockSupported;
+	}
+});
 Object.defineProperty(exports, "normalizeReadPagination", {
 	enumerable: true,
 	get: function() {
@@ -9203,6 +10429,12 @@ Object.defineProperty(exports, "performStringReplacement", {
 		return performStringReplacement;
 	}
 });
+Object.defineProperty(exports, "pinnedSkillsValue", {
+	enumerable: true,
+	get: function() {
+		return pinnedSkillsValue;
+	}
+});
 Object.defineProperty(exports, "registerHarnessProfile", {
 	enumerable: true,
 	get: function() {
@@ -9215,12 +10447,24 @@ Object.defineProperty(exports, "resolveBackend", {
 		return resolveBackend;
 	}
 });
+Object.defineProperty(exports, "scrubUnsupportedMultimodalContent", {
+	enumerable: true,
+	get: function() {
+		return scrubUnsupportedMultimodalContent;
+	}
+});
 Object.defineProperty(exports, "serializeProfile", {
 	enumerable: true,
 	get: function() {
 		return serializeProfile;
 	}
 });
+Object.defineProperty(exports, "setRealpath", {
+	enumerable: true,
+	get: function() {
+		return setRealpath;
+	}
+});
 Object.defineProperty(exports, "skillsMetadataValue", {
 	enumerable: true,
 	get: function() {
@@ -9228,4 +10472,4 @@ Object.defineProperty(exports, "skillsMetadataValue", {
 	}
 });
 
-//# sourceMappingURL=langsmith-Bhg_Q4ZO.cjs.map
+//# sourceMappingURL=langsmith-DMOexB11.cjs.map