deepagents 1.14.1 → 1.15.0

package/dist/{langsmith-Bgi_Ta-k.js → langsmith-v_uskil7.js}

@@ -1,16 +1,38 @@
 import { AIMessage, HumanMessage, SystemMessage, ToolMessage, anthropicPromptCachingMiddleware, bedrockPromptCachingMiddleware, context, countTokensApproximately, createAgent, createMiddleware, humanInTheLoopMiddleware, todoListMiddleware, tool } from "langchain";
-import { Command, REMOVE_ALL_MESSAGES, ReducedValue, StateSchema, getConfig, getCurrentTaskInput, getStore, isCommand } from "@langchain/langgraph";
+import { ContextOverflowError } from "@langchain/core/errors";
+import { Command, Overwrite, REMOVE_ALL_MESSAGES, ReducedValue, StateSchema, getConfig, getCurrentTaskInput, getStore, isCommand } from "@langchain/langgraph";
 import { z } from "zod/v4";
 import micromatch from "micromatch";
+import { createHash } from "node:crypto";
 import { AIMessage as AIMessage$1, HumanMessage as HumanMessage$1, RemoveMessage, SystemMessage as SystemMessage$1, ToolMessage as ToolMessage$1, getBufferString } from "@langchain/core/messages";
 import * as z$2 from "zod";
 import { z as z$1 } from "zod";
-import { ContextOverflowError } from "@langchain/core/errors";
 import { initChatModel } from "langchain/chat_models/universal";
 import yaml from "yaml";
+import { Runnable, RunnableBinding } from "@langchain/core/runnables";
+import { isLangChainTool } from "@langchain/core/tools";
+import { isOpenAITool } from "@langchain/core/language_models/base";
+import { convertToOpenAIFunction } from "@langchain/core/utils/function_calling";
+import { toJsonSchema } from "@langchain/core/utils/json_schema";
+import { isInteropZodSchema } from "@langchain/core/utils/types";
 import { Client } from "@langchain/langgraph-sdk";
 import { Client as Client$1 } from "langsmith";
 import { LangSmithResourceNotFoundError, LangSmithSandboxError, SandboxClient } from "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.
@@ -633,9 +655,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
 	});
@@ -786,8 +819,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;
@@ -1087,6 +1126,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 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 (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 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 (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 (!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 (ToolMessage.isInstance(message)) return new 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 (HumanMessage.isInstance(message)) return new HumanMessage({
+		content,
+		id: message.id,
+		additional_kwargs: message.additional_kwargs,
+		response_metadata: message.response_metadata
+	});
+	if (AIMessage.isInstance(message)) return new 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 (SystemMessage.isInstance(message)) return new 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 (!AIMessage$1.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 = ToolMessage$1.isInstance(message);
+		if (!isTool && !HumanMessage$1.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 ToolMessage$1({
+			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 HumanMessage$1({
+			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 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
@@ -1103,11 +1602,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("/")}`;
@@ -1157,14 +1658,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);
 	}
@@ -1178,6 +1680,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
@@ -1781,6 +2305,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.
 */
@@ -1942,25 +2468,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
@@ -2133,27 +2676,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 = context`
   Lists all files in a directory.
@@ -2241,13 +2813,13 @@ function getExecuteToolDescription(hasGrep, hasGlob) {
 function createLsTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return 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)`);
@@ -2270,23 +2842,17 @@ function createLsTool(backend, options) {
 function createReadFileTool(backend, options) {
 	const { customDescription, toolTokenLimitBeforeEvict, permissions } = options;
 	return 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");
@@ -2295,10 +2861,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,
@@ -2364,11 +2927,11 @@ function createReadFileTool(backend, options) {
 function createWriteFileTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return 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 ToolMessage({
 			content: `Successfully wrote to '${file_path}'`,
@@ -2396,11 +2959,11 @@ function createWriteFileTool(backend, options) {
 function createEditFileTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return 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 ToolMessage({
 			content: `Successfully replaced ${result.occurrences} occurrence(s) in '${file_path}'`,
@@ -2440,6 +3003,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);
@@ -2466,13 +3040,13 @@ function createDeleteTool(backend, options) {
 function createGlobTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return 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");
@@ -2492,14 +3066,14 @@ function createGlobTool(backend, options) {
 function createGrepTool(backend, options) {
 	const { customDescription, permissions, includeExecution, grepMaxCount } = options;
 	return 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");
@@ -2563,6 +3137,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 (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 (AIMessage.isInstance(messages[i])) {
+		lastResponseIndex = i;
+		break;
+	}
+	let changed = false;
+	const result = messages.map((message, index) => {
+		if (index <= lastResponseIndex || !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 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.
@@ -2589,7 +3225,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);
@@ -2726,18 +3365,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 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 (ToolMessage.isInstance(result)) {
 				const processed = await processToolMessage(result, request.runtime, request.state, request.toolCall?.id);
 				if (processed.filesUpdate) return new Command({ update: {
@@ -3585,10 +4265,12 @@ const EXCLUDED_STATE_KEYS = [
 	"todos",
 	"structuredResponse",
 	"skillsMetadata",
+	"pinnedSkills",
 	"memoryContents",
 	...CALL_COUNT_STATE_KEYS,
 	"_summarizationEvent",
 	"_summarizationSessionId",
+	"_skillToolsDisclosed",
 	FORKED_CONTEXT_KEY
 ];
 /**
@@ -3607,9 +4289,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.
@@ -3781,6 +4465,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(humanInTheLoopMiddleware({ interruptOn: spec.interruptOn }));
+	if (!middleware.some((m) => m.name === "UnsupportedContentMiddleware")) middleware.push(createUnsupportedContentMiddleware());
 	const selectedResponseFormat = options?.responseFormat ?? spec.responseFormat;
 	return createAgent({
 		model: spec.model,
@@ -4051,7 +4736,8 @@ function patchDanglingToolCalls(messages) {
 				patchedMessages.push(new ToolMessage({
 					content: toolMsg,
 					name: toolCall.name,
-					tool_call_id: toolCall.id
+					tool_call_id: toolCall.id,
+					status: "error"
 				}));
 			}
 		}
@@ -4493,6 +5179,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.
@@ -4552,6 +5278,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.
 */
@@ -4593,11 +5323,52 @@ const SkillMetadataEntrySchema = z$1.object({
 */
 const skillsMetadataValue = z$1.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 ReducedValue(z$1.array(z$1.string()).default(() => []), { reducer: (stored, written) => [...stored ?? [], ...written ?? []] });
+/**
 * State schema for skills middleware.
 */
 const SkillsStateSchema = new 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 ReducedValue(z$1.record(z$1.string(), z$1.string()).optional(), { reducer: (_previous, next) => next })
 });
 /**
 * Skills System Documentation prompt template.
@@ -4699,7 +5470,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).
@@ -4710,6 +5482,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;
@@ -4747,7 +5521,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;
@@ -4866,6 +5640,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 HumanMessage$1({
+		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).
 */
@@ -4925,6 +5754,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 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 (!AIMessage$1.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 (ToolMessage$1.isInstance(message) && message.status !== "error") path = readPaths.get(message.tool_call_id);
+		else if (HumanMessage$1.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 (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) && 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 = AIMessage$1.isInstance(message) && message.content.length === 0 && !message.tool_calls?.length;
+			if (!ToolMessage$1.isInstance(message) && !HumanMessage$1.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 SystemMessage$1({ 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 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: isInteropZodSchema(tool.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",
+			...convertToOpenAIFunction(tool)
+		}]
+	};
+}
 /**
 * Create backend-agnostic middleware for loading and exposing agent skills.
 *
@@ -4948,8 +6107,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
@@ -4961,30 +6174,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 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 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 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
 			});
 		}
 	});
@@ -5754,46 +6997,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
@@ -6659,13 +7862,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({
@@ -6674,23 +7874,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,
@@ -6700,11 +7910,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));
@@ -6717,16 +7928,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,
@@ -6745,7 +7952,6 @@ function createDeepAgent(params = {}) {
 		createPatchToolCallsMiddleware()
 	];
 	let middleware = mergeMiddlewareStack([
-		...skillsMiddleware,
 		fsMiddleware,
 		subagentMiddleware,
 		summarizationMiddleware,
@@ -6753,6 +7959,7 @@ function createDeepAgent(params = {}) {
 		...asyncSubAgents.length > 0 ? [createAsyncSubAgentMiddleware({ asyncSubAgents })] : []
 	], customMiddleware, [
 		...resolveMiddleware(harnessProfile.extraMiddleware),
+		...skillsMiddleware,
 		...cacheMiddleware,
 		...memoryMiddleware,
 		...interruptOn ? [humanInTheLoopMiddleware({ interruptOn })] : []
@@ -6762,6 +7969,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)
@@ -8879,6 +10087,6 @@ var LangSmithSandbox = class LangSmithSandbox extends BaseSandbox {
 	}
 };
 //#endregion
-export { performStringReplacement as $, createPatchToolCallsMiddleware as A, CompositeBackend as B, MAX_SKILL_DESCRIPTION_LENGTH as C, skillsMetadataValue as D, createSkillsMiddleware as E, createSubAgent as F, isSandboxProtocol as G, SandboxError as H, createSubAgentMiddleware as I, adaptSandboxProtocol as J, resolveBackend as K, computeSummarizationDefaults as L, DEFAULT_SUBAGENT_PROMPT as M, GENERAL_PURPOSE_SUBAGENT as N, createMemoryMiddleware as O, SUBAGENT_RESPONSE_FORMAT_CONFIG_KEY as P, normalizeReadPagination as Q, createSummarizationMiddleware as R, createCompletionCallbackMiddleware as S, MAX_SKILL_NAME_LENGTH as T, applyGrepMaxCount as U, StateBackend as V, isSandboxBackend as W, getMimeType as X, checkEmptyContent as Y, isTextMimeType as Z, createHarnessProfile as _, ASYNC_TASK_SYSTEM_PROMPT as a, createAsyncSubAgentMiddleware as b, TASK_SYSTEM_PROMPT as c, registerHarnessProfile as d, generalPurposeSubagentConfigSchema as f, EMPTY_HARNESS_PROFILE as g, serializeProfile as h, StoreBackend as i, DEFAULT_GENERAL_PURPOSE_DESCRIPTION as j, filesValue as k, createDeepAgent as l, parseHarnessProfileConfig as m, BaseSandbox as n, BASE_AGENT_PROMPT as o, harnessProfileConfigSchema as p, adaptBackendProtocol as q, ContextHubBackend as r, EXECUTION_SYSTEM_PROMPT as s, LangSmithSandbox as t, getHarnessProfile as u, REQUIRED_MIDDLEWARE_NAMES as v, MAX_SKILL_FILE_SIZE as w, isAsyncSubAgent as x, ConfigurationError as y, createFilesystemMiddleware as z };
+export { adaptSandboxProtocol as $, filesValue as A, createFilesystemMiddleware as B, MAX_SKILL_FILE_SIZE as C, skillsMetadataValue as D, pinnedSkillsValue as E, SUBAGENT_RESPONSE_FORMAT_CONFIG_KEY as F, scrubUnsupportedMultimodalContent as G, MULTIMODAL_BLOCK_TYPES as H, createSubAgent as I, applyGrepMaxCount as J, StateBackend as K, createSubAgentMiddleware as L, DEFAULT_GENERAL_PURPOSE_DESCRIPTION as M, DEFAULT_SUBAGENT_PROMPT as N, ConfigurationError as O, GENERAL_PURPOSE_SUBAGENT as P, adaptBackendProtocol as Q, computeSummarizationDefaults as R, MAX_SKILL_DESCRIPTION_LENGTH as S, createSkillsMiddleware as T, createUnsupportedContentMiddleware as U, CompositeBackend as V, multimodalBlockSupported as W, isSandboxProtocol as X, isSandboxBackend as Y, resolveBackend as Z, createHarnessProfile as _, ASYNC_TASK_SYSTEM_PROMPT as a, setRealpath as at, isAsyncSubAgent as b, TASK_SYSTEM_PROMPT as c, registerHarnessProfile as d, checkEmptyContent as et, generalPurposeSubagentConfigSchema as f, EMPTY_HARNESS_PROFILE as g, serializeProfile as h, StoreBackend as i, performStringReplacement as it, createPatchToolCallsMiddleware as j, createMemoryMiddleware as k, createDeepAgent as l, parseHarnessProfileConfig as m, BaseSandbox as n, isTextMimeType as nt, BASE_AGENT_PROMPT as o, harnessProfileConfigSchema as p, SandboxError as q, ContextHubBackend as r, normalizeReadPagination as rt, EXECUTION_SYSTEM_PROMPT as s, LangSmithSandbox as t, getMimeType as tt, getHarnessProfile as u, REQUIRED_MIDDLEWARE_NAMES as v, MAX_SKILL_NAME_LENGTH as w, createCompletionCallbackMiddleware as x, createAsyncSubAgentMiddleware as y, createSummarizationMiddleware as z };
 
-//# sourceMappingURL=langsmith-Bgi_Ta-k.js.map
+//# sourceMappingURL=langsmith-v_uskil7.js.map