@librechat/agents 3.2.38 → 3.2.41

package/dist/esm/messages/anthropicToolCache.mjs

@@ -1,3 +1,4 @@
+import { buildAnthropicCacheControl } from "./cache.mjs";
 //#region src/messages/anthropicToolCache.ts
 const ANTHROPIC_BUILT_IN_TOOL_PREFIXES = [
 	"text_editor_",
@@ -12,25 +13,69 @@ const ANTHROPIC_BUILT_IN_TOOL_PREFIXES = [
 	"tool_search_",
 	"mcp_toolset"
 ];
-const CACHE_CONTROL = { type: "ephemeral" };
 function isAnthropicBuiltInTool(tool) {
 	const { type } = tool;
 	return typeof type === "string" && ANTHROPIC_BUILT_IN_TOOL_PREFIXES.some((prefix) => type.startsWith(prefix));
 }
+/**
+* Whether a tool already carries a cache breakpoint. Built-ins use a direct
+* `cache_control`; custom tools normally carry it under `extras`, but a
+* caller-supplied Anthropic-native tool object can also put it directly on the
+* block — check both so stale markers are never missed.
+*/
 function hasCacheControl(tool) {
 	if (isAnthropicBuiltInTool(tool)) return tool.cache_control != null;
-	return tool.extras?.cache_control != null;
+	return tool.cache_control != null || tool.extras?.cache_control != null;
+}
+/**
+* Return the `cache_control` from the location that actually reaches the
+* Anthropic payload for this tool's shape: directly on the block for
+* provider-shaped tools (built-ins and raw Anthropic tools), or under `extras`
+* for LangChain custom tools (the adapter promotes only that). Returns
+* `undefined` when no marker sits in the effective location — a marker in the
+* wrong place (e.g. a direct marker on a custom tool) does not count.
+*/
+function getEffectiveCacheControl(tool) {
+	return isProviderShapedTool(tool) ? tool.cache_control : tool.extras?.cache_control;
 }
-function markCacheControl(tool) {
+/**
+* Return a clone of `tool` with any `cache_control` removed — both the direct
+* block marker and the `extras` marker — preserving the prototype chain. Used
+* to clear stray markers off tools that must not anchor a competing breakpoint.
+*/
+function stripCacheControl(tool) {
 	const prototype = Object.getPrototypeOf(tool) ?? Object.prototype;
-	if (isAnthropicBuiltInTool(tool)) {
+	const wrapped = { ...tool };
+	delete wrapped.cache_control;
+	if (wrapped.extras != null) {
+		wrapped.extras = { ...wrapped.extras };
+		delete wrapped.extras.cache_control;
+	}
+	return Object.assign(Object.create(prototype), wrapped);
+}
+/**
+* Whether `tool` is already in the Anthropic provider payload shape — an
+* Anthropic built-in or a raw Anthropic tool object (has `input_schema`). These
+* carry `cache_control` directly on the block; the LangChain adapter does NOT
+* promote `extras.cache_control` for them. LangChain StructuredTools, by
+* contrast, expose the marker via `extras`.
+*/
+function isProviderShapedTool(tool) {
+	return isAnthropicBuiltInTool(tool) || "input_schema" in tool;
+}
+function markCacheControl(tool, ttl) {
+	const cacheControl = buildAnthropicCacheControl(ttl);
+	const prototype = Object.getPrototypeOf(tool) ?? Object.prototype;
+	if (isProviderShapedTool(tool)) {
 		const wrapped = { ...tool };
 		delete wrapped.extras;
-		return Object.assign(Object.create(prototype), wrapped, { cache_control: CACHE_CONTROL });
+		return Object.assign(Object.create(prototype), wrapped, { cache_control: cacheControl });
 	}
-	return Object.assign(Object.create(prototype), tool, { extras: {
+	const wrapped = { ...tool };
+	delete wrapped.cache_control;
+	return Object.assign(Object.create(prototype), wrapped, { extras: {
 		...tool.extras ?? {},
-		cache_control: CACHE_CONTROL
+		cache_control: cacheControl
 	} });
 }
 /**
@@ -59,7 +104,7 @@ function makeIsDeferred(toolDefinitions) {
 * `instanceof` checks still pass. For custom tools, `extras` is merged
 * so any existing `providerToolDefinition` / other extras are kept.
 */
-function partitionAndMarkAnthropicToolCache(tools, isDeferred) {
+function partitionAndMarkAnthropicToolCache(tools, isDeferred, ttl) {
 	if (tools == null || tools.length === 0) return tools;
 	const staticTools = [];
 	const deferredTools = [];
@@ -68,13 +113,30 @@ function partitionAndMarkAnthropicToolCache(tools, isDeferred) {
 		if (typeof name === "string" && isDeferred(name)) deferredTools.push(tool);
 		else staticTools.push(tool);
 	}
-	if (staticTools.length === 0) return tools;
+	let mutated = false;
+	for (let i = 0; i < deferredTools.length; i++) {
+		const candidate = deferredTools[i];
+		if (hasCacheControl(candidate)) {
+			deferredTools[i] = stripCacheControl(candidate);
+			mutated = true;
+		}
+	}
+	if (staticTools.length === 0) return mutated ? [...deferredTools] : tools;
+	for (let i = 0; i < staticTools.length - 1; i++) {
+		const candidate = staticTools[i];
+		if (hasCacheControl(candidate)) {
+			staticTools[i] = stripCacheControl(candidate);
+			mutated = true;
+		}
+	}
 	const last = staticTools[staticTools.length - 1];
-	if (hasCacheControl(last)) {
-		if (deferredTools.length === 0) return tools;
-		return [...staticTools, ...deferredTools];
+	const desiredTtl = ttl === "1h" ? "1h" : void 0;
+	const effective = getEffectiveCacheControl(last);
+	if (!(effective != null && (effective.ttl === "1h" ? "1h" : void 0) === desiredTtl)) {
+		staticTools[staticTools.length - 1] = markCacheControl(last, ttl);
+		mutated = true;
 	}
-	staticTools[staticTools.length - 1] = markCacheControl(last);
+	if (!mutated && deferredTools.length === 0) return tools;
 	return [...staticTools, ...deferredTools];
 }
 //#endregion

package/dist/esm/messages/anthropicToolCache.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"anthropicToolCache.mjs","names":[],"sources":["../../../src/messages/anthropicToolCache.ts"],"sourcesContent":["/**\n * Anthropic prompt-caching helper for the `tools[]` request field.\n *\n * Anthropic accepts `cache_control: { type: 'ephemeral' }` on individual\n * tool definitions. Whichever tool carries the marker becomes the end of\n * a cached prefix: `tools[0..N]` (everything up to and including the\n * marked tool) is cached and rebated on subsequent matching requests.\n *\n * For agents that mix static and deferred (lazily-discovered) tools, the\n * winning configuration is:\n *\n *   1. Stable-partition tools so all *static* (non-deferred) tools come\n *      first and discovered-deferred tools come last.\n *   2. Stamp `cache_control` on the LAST static tool.\n *\n * That way, the cached prefix covers exactly the static tool inventory.\n * Discovered tools that show up later (or vary turn-to-turn as new ones\n * get discovered) never invalidate the prefix because they sit *after*\n * the breakpoint.\n *\n * LangChain's Anthropic adapter passes the marker through via\n * `tool.extras.cache_control` for custom tools, while Anthropic built-ins\n * require direct `cache_control`. Either way, we stamp a fresh wrapper —\n * never mutating the original tool instance, since callers may share them\n * across runs.\n */\n\nimport type { GraphTools } from '@/types';\n\nconst ANTHROPIC_BUILT_IN_TOOL_PREFIXES = [\n  'text_editor_',\n  'computer_',\n  'bash_',\n  'web_search_',\n  'web_fetch_',\n  'str_replace_editor_',\n  'str_replace_based_edit_tool_',\n  'code_execution_',\n  'memory_',\n  'tool_search_',\n  'mcp_toolset',\n] as const;\n\nconst CACHE_CONTROL = { type: 'ephemeral' as const };\n\ntype AnthropicToolCacheCandidate = {\n  name?: unknown;\n  type?: unknown;\n  extras?: Record<string, unknown>;\n  cache_control?: unknown;\n};\n\nfunction isAnthropicBuiltInTool(\n  tool: AnthropicToolCacheCandidate\n): tool is AnthropicToolCacheCandidate & { type: string } {\n  const { type } = tool;\n  return (\n    typeof type === 'string' &&\n    ANTHROPIC_BUILT_IN_TOOL_PREFIXES.some((prefix) => type.startsWith(prefix))\n  );\n}\n\nfunction hasCacheControl(tool: AnthropicToolCacheCandidate): boolean {\n  if (isAnthropicBuiltInTool(tool)) {\n    return tool.cache_control != null;\n  }\n  return tool.extras?.cache_control != null;\n}\n\nfunction markCacheControl(\n  tool: AnthropicToolCacheCandidate\n): AnthropicToolCacheCandidate {\n  const prototype = Object.getPrototypeOf(tool) ?? Object.prototype;\n  if (isAnthropicBuiltInTool(tool)) {\n    const wrapped = { ...tool };\n    delete wrapped.extras;\n    return Object.assign(Object.create(prototype), wrapped, {\n      cache_control: CACHE_CONTROL,\n    });\n  }\n\n  return Object.assign(Object.create(prototype), tool, {\n    extras: {\n      ...(tool.extras ?? {}),\n      cache_control: CACHE_CONTROL,\n    },\n  });\n}\n\n/**\n * Returns a callable that reports whether a given tool *name* is deferred\n * according to the supplied registry of tool definitions. Tools without\n * a registry entry are treated as non-deferred (i.e. static), matching\n * the host-supplied `graphTools` semantics elsewhere in the SDK.\n */\nexport function makeIsDeferred(\n  toolDefinitions:\n    | ReadonlyArray<{ name: string; defer_loading?: boolean }>\n    | undefined\n): (toolName: string) => boolean {\n  if (toolDefinitions == null || toolDefinitions.length === 0) {\n    return () => false;\n  }\n  const deferred = new Set<string>();\n  for (const def of toolDefinitions) {\n    if (def.defer_loading === true) deferred.add(def.name);\n  }\n  if (deferred.size === 0) return () => false;\n  return (name) => deferred.has(name);\n}\n\n/**\n * Stable-partition `tools` into [static..., deferred...] and stamp the\n * Anthropic `cache_control: ephemeral` marker on the last static tool.\n *\n * If `tools` is undefined or empty, or no entry has a usable `.name`,\n * returns the input unchanged. If there are no static tools at all,\n * also returns unchanged (nothing to cache).\n *\n * The original tool instances are never mutated. The marked entry is a\n * shallow wrapper that preserves the prototype chain so downstream\n * `instanceof` checks still pass. For custom tools, `extras` is merged\n * so any existing `providerToolDefinition` / other extras are kept.\n */\nexport function partitionAndMarkAnthropicToolCache(\n  tools: GraphTools | undefined,\n  isDeferred: (toolName: string) => boolean\n): GraphTools | undefined {\n  if (tools == null || tools.length === 0) return tools;\n\n  // Use unknown[] internally to avoid GraphTools' union-array variance\n  // (each member is one of three array types). We cast back to\n  // GraphTools when returning.\n  const staticTools: unknown[] = [];\n  const deferredTools: unknown[] = [];\n\n  for (const tool of tools) {\n    const name = (tool as { name?: unknown }).name;\n    if (typeof name === 'string' && isDeferred(name)) {\n      deferredTools.push(tool);\n    } else {\n      staticTools.push(tool);\n    }\n  }\n\n  if (staticTools.length === 0) {\n    return tools;\n  }\n\n  const last = staticTools[\n    staticTools.length - 1\n  ] as AnthropicToolCacheCandidate;\n  // Already marked? Don't double-clone.\n  if (hasCacheControl(last)) {\n    if (deferredTools.length === 0) return tools;\n    return [...staticTools, ...deferredTools] as GraphTools;\n  }\n\n  staticTools[staticTools.length - 1] = markCacheControl(last);\n  return [...staticTools, ...deferredTools] as GraphTools;\n}\n"],"mappings":";AA6BA,MAAM,mCAAmC;CACvC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;AAEA,MAAM,gBAAgB,EAAE,MAAM,YAAqB;AASnD,SAAS,uBACP,MACwD;CACxD,MAAM,EAAE,SAAS;CACjB,OACE,OAAO,SAAS,YAChB,iCAAiC,MAAM,WAAW,KAAK,WAAW,MAAM,CAAC;AAE7E;AAEA,SAAS,gBAAgB,MAA4C;CACnE,IAAI,uBAAuB,IAAI,GAC7B,OAAO,KAAK,iBAAiB;CAE/B,OAAO,KAAK,QAAQ,iBAAiB;AACvC;AAEA,SAAS,iBACP,MAC6B;CAC7B,MAAM,YAAY,OAAO,eAAe,IAAI,KAAK,OAAO;CACxD,IAAI,uBAAuB,IAAI,GAAG;EAChC,MAAM,UAAU,EAAE,GAAG,KAAK;EAC1B,OAAO,QAAQ;EACf,OAAO,OAAO,OAAO,OAAO,OAAO,SAAS,GAAG,SAAS,EACtD,eAAe,cACjB,CAAC;CACH;CAEA,OAAO,OAAO,OAAO,OAAO,OAAO,SAAS,GAAG,MAAM,EACnD,QAAQ;EACN,GAAI,KAAK,UAAU,CAAC;EACpB,eAAe;CACjB,EACF,CAAC;AACH;;;;;;;AAQA,SAAgB,eACd,iBAG+B;CAC/B,IAAI,mBAAmB,QAAQ,gBAAgB,WAAW,GACxD,aAAa;CAEf,MAAM,2BAAW,IAAI,IAAY;CACjC,KAAK,MAAM,OAAO,iBAChB,IAAI,IAAI,kBAAkB,MAAM,SAAS,IAAI,IAAI,IAAI;CAEvD,IAAI,SAAS,SAAS,GAAG,aAAa;CACtC,QAAQ,SAAS,SAAS,IAAI,IAAI;AACpC;;;;;;;;;;;;;;AAeA,SAAgB,mCACd,OACA,YACwB;CACxB,IAAI,SAAS,QAAQ,MAAM,WAAW,GAAG,OAAO;CAKhD,MAAM,cAAyB,CAAC;CAChC,MAAM,gBAA2B,CAAC;CAElC,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,OAAQ,KAA4B;EAC1C,IAAI,OAAO,SAAS,YAAY,WAAW,IAAI,GAC7C,cAAc,KAAK,IAAI;OAEvB,YAAY,KAAK,IAAI;CAEzB;CAEA,IAAI,YAAY,WAAW,GACzB,OAAO;CAGT,MAAM,OAAO,YACX,YAAY,SAAS;CAGvB,IAAI,gBAAgB,IAAI,GAAG;EACzB,IAAI,cAAc,WAAW,GAAG,OAAO;EACvC,OAAO,CAAC,GAAG,aAAa,GAAG,aAAa;CAC1C;CAEA,YAAY,YAAY,SAAS,KAAK,iBAAiB,IAAI;CAC3D,OAAO,CAAC,GAAG,aAAa,GAAG,aAAa;AAC1C"}
+{"version":3,"file":"anthropicToolCache.mjs","names":[],"sources":["../../../src/messages/anthropicToolCache.ts"],"sourcesContent":["/**\n * Anthropic prompt-caching helper for the `tools[]` request field.\n *\n * Anthropic accepts `cache_control: { type: 'ephemeral' }` on individual\n * tool definitions. Whichever tool carries the marker becomes the end of\n * a cached prefix: `tools[0..N]` (everything up to and including the\n * marked tool) is cached and rebated on subsequent matching requests.\n *\n * For agents that mix static and deferred (lazily-discovered) tools, the\n * winning configuration is:\n *\n *   1. Stable-partition tools so all *static* (non-deferred) tools come\n *      first and discovered-deferred tools come last.\n *   2. Stamp `cache_control` on the LAST static tool.\n *\n * That way, the cached prefix covers exactly the static tool inventory.\n * Discovered tools that show up later (or vary turn-to-turn as new ones\n * get discovered) never invalidate the prefix because they sit *after*\n * the breakpoint.\n *\n * LangChain's Anthropic adapter passes the marker through via\n * `tool.extras.cache_control` for custom tools, while Anthropic built-ins\n * require direct `cache_control`. Either way, we stamp a fresh wrapper —\n * never mutating the original tool instance, since callers may share them\n * across runs.\n */\n\nimport type { GraphTools } from '@/types';\nimport {\n  buildAnthropicCacheControl,\n  type PromptCacheTtl,\n} from '@/messages/cache';\n\nconst ANTHROPIC_BUILT_IN_TOOL_PREFIXES = [\n  'text_editor_',\n  'computer_',\n  'bash_',\n  'web_search_',\n  'web_fetch_',\n  'str_replace_editor_',\n  'str_replace_based_edit_tool_',\n  'code_execution_',\n  'memory_',\n  'tool_search_',\n  'mcp_toolset',\n] as const;\n\ntype AnthropicToolCacheCandidate = {\n  name?: unknown;\n  type?: unknown;\n  extras?: Record<string, unknown>;\n  cache_control?: unknown;\n};\n\nfunction isAnthropicBuiltInTool(\n  tool: AnthropicToolCacheCandidate\n): tool is AnthropicToolCacheCandidate & { type: string } {\n  const { type } = tool;\n  return (\n    typeof type === 'string' &&\n    ANTHROPIC_BUILT_IN_TOOL_PREFIXES.some((prefix) => type.startsWith(prefix))\n  );\n}\n\n/**\n * Whether a tool already carries a cache breakpoint. Built-ins use a direct\n * `cache_control`; custom tools normally carry it under `extras`, but a\n * caller-supplied Anthropic-native tool object can also put it directly on the\n * block — check both so stale markers are never missed.\n */\nfunction hasCacheControl(tool: AnthropicToolCacheCandidate): boolean {\n  if (isAnthropicBuiltInTool(tool)) {\n    return tool.cache_control != null;\n  }\n  return tool.cache_control != null || tool.extras?.cache_control != null;\n}\n\n/**\n * Return the `cache_control` from the location that actually reaches the\n * Anthropic payload for this tool's shape: directly on the block for\n * provider-shaped tools (built-ins and raw Anthropic tools), or under `extras`\n * for LangChain custom tools (the adapter promotes only that). Returns\n * `undefined` when no marker sits in the effective location — a marker in the\n * wrong place (e.g. a direct marker on a custom tool) does not count.\n */\nfunction getEffectiveCacheControl(\n  tool: AnthropicToolCacheCandidate\n): { ttl?: unknown } | undefined {\n  return (\n    isProviderShapedTool(tool) ? tool.cache_control : tool.extras?.cache_control\n  ) as { ttl?: unknown } | undefined;\n}\n\n/**\n * Return a clone of `tool` with any `cache_control` removed — both the direct\n * block marker and the `extras` marker — preserving the prototype chain. Used\n * to clear stray markers off tools that must not anchor a competing breakpoint.\n */\nfunction stripCacheControl(\n  tool: AnthropicToolCacheCandidate\n): AnthropicToolCacheCandidate {\n  const prototype = Object.getPrototypeOf(tool) ?? Object.prototype;\n  const wrapped = { ...tool };\n  delete wrapped.cache_control;\n  if (wrapped.extras != null) {\n    wrapped.extras = { ...wrapped.extras };\n    delete wrapped.extras.cache_control;\n  }\n  return Object.assign(Object.create(prototype), wrapped);\n}\n\n/**\n * Whether `tool` is already in the Anthropic provider payload shape — an\n * Anthropic built-in or a raw Anthropic tool object (has `input_schema`). These\n * carry `cache_control` directly on the block; the LangChain adapter does NOT\n * promote `extras.cache_control` for them. LangChain StructuredTools, by\n * contrast, expose the marker via `extras`.\n */\nfunction isProviderShapedTool(tool: AnthropicToolCacheCandidate): boolean {\n  return (\n    isAnthropicBuiltInTool(tool) ||\n    'input_schema' in (tool as Record<string, unknown>)\n  );\n}\n\nfunction markCacheControl(\n  tool: AnthropicToolCacheCandidate,\n  ttl?: PromptCacheTtl\n): AnthropicToolCacheCandidate {\n  const cacheControl = buildAnthropicCacheControl(ttl);\n  const prototype = Object.getPrototypeOf(tool) ?? Object.prototype;\n  if (isProviderShapedTool(tool)) {\n    // Built-ins and raw Anthropic tool objects carry cache_control directly on\n    // the block; `extras` is not promoted onto the payload for these shapes.\n    const wrapped = { ...tool };\n    delete wrapped.extras;\n    return Object.assign(Object.create(prototype), wrapped, {\n      cache_control: cacheControl,\n    });\n  }\n\n  // LangChain custom tools: drop any direct marker and expose the breakpoint via\n  // `extras`, which the Anthropic adapter promotes onto the payload.\n  const wrapped = { ...tool };\n  delete wrapped.cache_control;\n  return Object.assign(Object.create(prototype), wrapped, {\n    extras: {\n      ...(tool.extras ?? {}),\n      cache_control: cacheControl,\n    },\n  });\n}\n\n/**\n * Returns a callable that reports whether a given tool *name* is deferred\n * according to the supplied registry of tool definitions. Tools without\n * a registry entry are treated as non-deferred (i.e. static), matching\n * the host-supplied `graphTools` semantics elsewhere in the SDK.\n */\nexport function makeIsDeferred(\n  toolDefinitions:\n    | ReadonlyArray<{ name: string; defer_loading?: boolean }>\n    | undefined\n): (toolName: string) => boolean {\n  if (toolDefinitions == null || toolDefinitions.length === 0) {\n    return () => false;\n  }\n  const deferred = new Set<string>();\n  for (const def of toolDefinitions) {\n    if (def.defer_loading === true) deferred.add(def.name);\n  }\n  if (deferred.size === 0) return () => false;\n  return (name) => deferred.has(name);\n}\n\n/**\n * Stable-partition `tools` into [static..., deferred...] and stamp the\n * Anthropic `cache_control: ephemeral` marker on the last static tool.\n *\n * If `tools` is undefined or empty, or no entry has a usable `.name`,\n * returns the input unchanged. If there are no static tools at all,\n * also returns unchanged (nothing to cache).\n *\n * The original tool instances are never mutated. The marked entry is a\n * shallow wrapper that preserves the prototype chain so downstream\n * `instanceof` checks still pass. For custom tools, `extras` is merged\n * so any existing `providerToolDefinition` / other extras are kept.\n */\nexport function partitionAndMarkAnthropicToolCache(\n  tools: GraphTools | undefined,\n  isDeferred: (toolName: string) => boolean,\n  ttl?: PromptCacheTtl\n): GraphTools | undefined {\n  if (tools == null || tools.length === 0) return tools;\n\n  // Use unknown[] internally to avoid GraphTools' union-array variance\n  // (each member is one of three array types). We cast back to\n  // GraphTools when returning.\n  const staticTools: unknown[] = [];\n  const deferredTools: unknown[] = [];\n\n  for (const tool of tools) {\n    const name = (tool as { name?: unknown }).name;\n    if (typeof name === 'string' && isDeferred(name)) {\n      deferredTools.push(tool);\n    } else {\n      staticTools.push(tool);\n    }\n  }\n\n  // Anthropic serializes ALL tools before system/messages, so a stray\n  // cache_control on any tool — static or deferred — that survives the resolved\n  // breakpoint would violate the longer-TTL-first ordering. Strip stale markers\n  // off the deferred tools first (they sit after the breakpoint but still before\n  // system/messages, and the all-deferred case has no breakpoint of its own).\n  let mutated = false;\n  for (let i = 0; i < deferredTools.length; i++) {\n    const candidate = deferredTools[i] as AnthropicToolCacheCandidate;\n    if (hasCacheControl(candidate)) {\n      deferredTools[i] = stripCacheControl(candidate);\n      mutated = true;\n    }\n  }\n\n  if (staticTools.length === 0) {\n    return mutated ? ([...deferredTools] as GraphTools) : tools;\n  }\n\n  // Strip any stray cache_control off the earlier static tools so a leftover\n  // 5-minute marker never sits ahead of the resolved breakpoint, then stamp (or\n  // re-stamp) only the last static tool with the resolved TTL.\n  for (let i = 0; i < staticTools.length - 1; i++) {\n    const candidate = staticTools[i] as AnthropicToolCacheCandidate;\n    if (hasCacheControl(candidate)) {\n      staticTools[i] = stripCacheControl(candidate);\n      mutated = true;\n    }\n  }\n\n  const last = staticTools[\n    staticTools.length - 1\n  ] as AnthropicToolCacheCandidate;\n  const desiredTtl: '1h' | undefined = ttl === '1h' ? '1h' : undefined;\n  // \"Already correct\" requires a marker IN the effective location (one that\n  // reaches the payload for this tool's shape) carrying the resolved TTL. A\n  // marker in the wrong place — e.g. a direct `cache_control` on a LangChain\n  // custom tool — is ineffective and must be re-stamped.\n  const effective = getEffectiveCacheControl(last);\n  const lastAlreadyCorrect =\n    effective != null &&\n    (effective.ttl === '1h' ? '1h' : undefined) === desiredTtl;\n  if (!lastAlreadyCorrect) {\n    staticTools[staticTools.length - 1] = markCacheControl(last, ttl);\n    mutated = true;\n  }\n\n  // Return the original reference only when nothing changed AND partitioning\n  // moved nothing. When deferred tools exist they must end up after the cache\n  // breakpoint, so the partitioned array is returned even if no marker changed.\n  if (!mutated && deferredTools.length === 0) {\n    return tools;\n  }\n  return [...staticTools, ...deferredTools] as GraphTools;\n}\n"],"mappings":"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"}

package/dist/esm/messages/cache.mjs

@@ -4,6 +4,42 @@ import { withMessageRole } from "./format.mjs";
 import { AIMessage, BaseMessage, HumanMessage, SystemMessage, ToolMessage } from "@langchain/core/messages";
 //#region src/messages/cache.ts
 /**
+* Default TTL applied wherever a prompt-cache breakpoint is added. The 1-hour
+* extended cache keeps prefixes warm across longer gaps between turns, at the
+* cost of a higher one-time cache-write multiplier (2x vs 1.25x for 5m).
+*/
+const DEFAULT_PROMPT_CACHE_TTL = "1h";
+/**
+* Resolve an optionally-configured TTL to a concrete value, defaulting to the
+* 1-hour extended cache. Used at the Anthropic/Bedrock prompt-cache call sites.
+*/
+function resolvePromptCacheTtl(ttl) {
+	return ttl ?? "1h";
+}
+/**
+* Build an Anthropic `cache_control` breakpoint for the given TTL. `'5m'` (or
+* `undefined`) omits the `ttl` field — that is the provider default, so the
+* payload stays byte-identical to the legacy 5-minute marker. `'1h'` adds the
+* explicit extended-cache `ttl`.
+*/
+function buildAnthropicCacheControl(ttl) {
+	return ttl === "1h" ? {
+		type: "ephemeral",
+		ttl: "1h"
+	} : { type: "ephemeral" };
+}
+/**
+* Build a Bedrock `cachePoint` for the given TTL. Mirrors
+* {@link buildAnthropicCacheControl}: `'5m'`/`undefined` omits `ttl` (the
+* legacy default), `'1h'` adds the extended-cache `ttl`.
+*/
+function buildBedrockCachePoint(ttl) {
+	return ttl === "1h" ? {
+		type: "default",
+		ttl: "1h"
+	} : { type: "default" };
+}
+/**
 * Deep clones a message's content to prevent mutation of the original.
 */
 function deepCloneContent(content) {
@@ -56,25 +92,41 @@ function cloneMessage(message, content) {
 	}
 	return cloned;
 }
-function stripAnthropicCacheControlFromBlocks(content) {
+/**
+* Sanitize a Bedrock system message: strip Anthropic `cache_control` (Bedrock
+* conversion can't use it) and normalize any existing `cachePoint` to the
+* resolved TTL. The normalization matters because Bedrock requires longer-TTL
+* checkpoints to appear before shorter ones — a stale 5-minute system cachePoint
+* (host-supplied or carried over from a 5m config) left ahead of a 1-hour
+* message tail would make the request invalid. System messages are never
+* anchored as the tail breakpoint; this only fixes markers already present.
+*/
+function sanitizeBedrockSystemMessage(message, ttl) {
+	const content = message.content;
+	if (!Array.isArray(content)) return message;
+	const sanitized = [];
 	let modified = false;
-	return {
-		content: content.map((block) => {
-			if (!("cache_control" in block)) return block;
+	for (const block of content) {
+		if (isCachePoint(block)) {
+			const existing = block.cachePoint;
+			const desired = buildBedrockCachePoint(ttl);
+			if (existing?.ttl !== desired.ttl) {
+				modified = true;
+				sanitized.push({ cachePoint: desired });
+			} else sanitized.push(block);
+			continue;
+		}
+		if ("cache_control" in block) {
 			const cloned = { ...block };
 			delete cloned.cache_control;
 			modified = true;
-			return cloned;
-		}),
-		modified
-	};
-}
-function sanitizeBedrockSystemMessage(message) {
-	const content = message.content;
-	if (!Array.isArray(content)) return message;
-	const stripped = stripAnthropicCacheControlFromBlocks(content);
-	if (!stripped.modified) return message;
-	return cloneMessage(message, stripped.content);
+			sanitized.push(cloned);
+			continue;
+		}
+		sanitized.push(block);
+	}
+	if (!modified) return message;
+	return cloneMessage(message, sanitized);
 }
 /**
 * Anthropic API: Adds cache control to the appropriate user messages in the payload.
@@ -85,7 +137,7 @@ function sanitizeBedrockSystemMessage(message) {
 * @param messages - The array of message objects.
 * @returns - A new array of message objects with cache control added.
 */
-function addCacheControl(messages) {
+function addCacheControl(messages, ttl) {
 	if (!Array.isArray(messages) || messages.length < 2) return messages;
 	const updatedMessages = [...messages];
 	let userMessagesModified = 0;
@@ -118,14 +170,14 @@ function addCacheControl(messages) {
 			}
 			if (!modified && !needsCacheAdd) continue;
 			if (needsCacheAdd && lastTextIndex >= 0) {
-				workingContent[lastTextIndex].cache_control = { type: "ephemeral" };
+				workingContent[lastTextIndex].cache_control = buildAnthropicCacheControl(ttl);
 				userMessagesModified++;
 			}
 		} else if (typeof content === "string" && needsCacheAdd) {
 			workingContent = [{
 				type: "text",
 				text: content,
-				cache_control: { type: "ephemeral" }
+				cache_control: buildAnthropicCacheControl(ttl)
 			}];
 			userMessagesModified++;
 		} else continue;
@@ -196,7 +248,7 @@ function isTailCacheableBlock(block) {
 *
 * Returns a new array; only messages that require modification are cloned.
 */
-function addTailCacheControl(messages) {
+function addTailCacheControl(messages, ttl) {
 	if (!Array.isArray(messages) || messages.length === 0) return messages;
 	const updatedMessages = [...messages];
 	let markerPlaced = false;
@@ -227,7 +279,7 @@ function addTailCacheControl(messages) {
 				workingContent.push(cloned);
 			}
 			if (canPlaceMarker && tailIndex >= 0) {
-				workingContent[tailIndex].cache_control = { type: "ephemeral" };
+				workingContent[tailIndex].cache_control = buildAnthropicCacheControl(ttl);
 				markerPlaced = true;
 				modified = true;
 			}
@@ -236,7 +288,7 @@ function addTailCacheControl(messages) {
 			workingContent = [{
 				type: "text",
 				text: content,
-				cache_control: { type: "ephemeral" }
+				cache_control: buildAnthropicCacheControl(ttl)
 			}];
 			markerPlaced = true;
 		} else continue;
@@ -273,7 +325,7 @@ function isAssistantConversationMessage(message) {
 function hasCacheMarker(message) {
 	return Array.isArray(message.content) && message.content.some((block) => "cache_control" in block);
 }
-function addCacheControlToRecentMessages(messages, maxCachePoints, canUseMessage) {
+function addCacheControlToRecentMessages(messages, maxCachePoints, canUseMessage, ttl) {
 	if (!Array.isArray(messages) || messages.length === 0 || maxCachePoints <= 0) return messages;
 	const updatedMessages = [...messages];
 	let cachePointsAdded = 0;
@@ -307,7 +359,7 @@ function addCacheControlToRecentMessages(messages, maxCachePoints, canUseMessage
 				workingContent.push(cloned);
 			}
 			if (canAddCache && lastNonEmptyTextIndex >= 0) {
-				workingContent[lastNonEmptyTextIndex].cache_control = { type: "ephemeral" };
+				workingContent[lastNonEmptyTextIndex].cache_control = buildAnthropicCacheControl(ttl);
 				cachePointsAdded++;
 				modified = true;
 			}
@@ -316,7 +368,7 @@ function addCacheControlToRecentMessages(messages, maxCachePoints, canUseMessage
 			workingContent = [{
 				type: "text",
 				text: content,
-				cache_control: { type: "ephemeral" }
+				cache_control: buildAnthropicCacheControl(ttl)
 			}];
 			cachePointsAdded++;
 		} else continue;
@@ -324,10 +376,10 @@ function addCacheControlToRecentMessages(messages, maxCachePoints, canUseMessage
 	}
 	return updatedMessages;
 }
-function addCacheControlToStablePrefixMessages(messages, maxCachePoints) {
-	const assistantMarked = addCacheControlToRecentMessages(messages, maxCachePoints, isAssistantConversationMessage);
+function addCacheControlToStablePrefixMessages(messages, maxCachePoints, ttl) {
+	const assistantMarked = addCacheControlToRecentMessages(messages, maxCachePoints, isAssistantConversationMessage, ttl);
 	if (assistantMarked.some(hasCacheMarker)) return assistantMarked;
-	return addCacheControlToRecentMessages(messages, maxCachePoints, isCacheableConversationMessage);
+	return addCacheControlToRecentMessages(messages, maxCachePoints, isCacheableConversationMessage, ttl);
 }
 /**
 * Checks if a message's content has Anthropic cache_control fields.
@@ -391,7 +443,7 @@ function stripBedrockCacheControl(messages) {
 * @param messages - The array of message objects.
 * @returns - A new array of message objects with cache points added.
 */
-function addBedrockCacheControl(messages) {
+function addBedrockCacheControl(messages, ttl) {
 	if (!Array.isArray(messages) || messages.length === 0) return messages;
 	const updatedMessages = [...messages];
 	let cachePointsAdded = 0;
@@ -400,7 +452,7 @@ function addBedrockCacheControl(messages) {
 		const messageType = "getType" in originalMessage && typeof originalMessage.getType === "function" ? originalMessage.getType() : void 0;
 		const messageRole = "role" in originalMessage && typeof originalMessage.role === "string" ? originalMessage.role : void 0;
 		if (messageType === "system" || messageRole === "system") {
-			updatedMessages[i] = sanitizeBedrockSystemMessage(originalMessage);
+			updatedMessages[i] = sanitizeBedrockSystemMessage(originalMessage, ttl);
 			continue;
 		}
 		const isToolMessage = messageType === "tool" || messageRole === "tool";
@@ -436,14 +488,14 @@ function addBedrockCacheControl(messages) {
 			}
 			if (!modified && !needsCacheAdd) continue;
 			if (needsCacheAdd && lastNonEmptyTextIndex >= 0) {
-				workingContent.splice(lastNonEmptyTextIndex + 1, 0, { cachePoint: { type: "default" } });
+				workingContent.splice(lastNonEmptyTextIndex + 1, 0, { cachePoint: buildBedrockCachePoint(ttl) });
 				cachePointsAdded++;
 			}
 		} else if (typeof content === "string" && needsCacheAdd) {
 			workingContent = [{
 				type: "text",
 				text: content
-			}, { cachePoint: { type: "default" } }];
+			}, { cachePoint: buildBedrockCachePoint(ttl) }];
 			cachePointsAdded++;
 		} else if (typeof content === "string" && hasSerializationProps) workingContent = content;
 		else continue;
@@ -468,7 +520,7 @@ function addBedrockCacheControl(messages) {
 *
 * Returns a new array - only clones messages that require modification.
 */
-function addBedrockTailCacheControl(messages) {
+function addBedrockTailCacheControl(messages, ttl) {
 	if (!Array.isArray(messages) || messages.length === 0) return messages;
 	const updatedMessages = [...messages];
 	let cachePointPlaced = false;
@@ -477,7 +529,7 @@ function addBedrockTailCacheControl(messages) {
 		const messageType = "getType" in originalMessage && typeof originalMessage.getType === "function" ? originalMessage.getType() : void 0;
 		const messageRole = "role" in originalMessage && typeof originalMessage.role === "string" ? originalMessage.role : void 0;
 		if (messageType === "system" || messageRole === "system") {
-			updatedMessages[i] = sanitizeBedrockSystemMessage(originalMessage);
+			updatedMessages[i] = sanitizeBedrockSystemMessage(originalMessage, ttl);
 			continue;
 		}
 		const content = originalMessage.content;
@@ -511,7 +563,7 @@ function addBedrockTailCacheControl(messages) {
 			}
 			if (!modified && !canPlaceCachePoint) continue;
 			if (canPlaceCachePoint && lastNonEmptyTextIndex >= 0) {
-				workingContent.splice(lastNonEmptyTextIndex + 1, 0, { cachePoint: { type: "default" } });
+				workingContent.splice(lastNonEmptyTextIndex + 1, 0, { cachePoint: buildBedrockCachePoint(ttl) });
 				cachePointPlaced = true;
 				modified = true;
 			}
@@ -519,7 +571,7 @@ function addBedrockTailCacheControl(messages) {
 			workingContent = [{
 				type: "text",
 				text: content
-			}, { cachePoint: { type: "default" } }];
+			}, { cachePoint: buildBedrockCachePoint(ttl) }];
 			cachePointPlaced = true;
 		} else if (typeof content === "string" && hasSerializationProps) workingContent = content;
 		else continue;
@@ -528,6 +580,6 @@ function addBedrockTailCacheControl(messages) {
 	return updatedMessages;
 }
 //#endregion
-export { addBedrockCacheControl, addBedrockTailCacheControl, addCacheControl, addCacheControlToStablePrefixMessages, addTailCacheControl, cloneMessage, stripAnthropicCacheControl, stripBedrockCacheControl };
+export { DEFAULT_PROMPT_CACHE_TTL, addBedrockCacheControl, addBedrockTailCacheControl, addCacheControl, addCacheControlToStablePrefixMessages, addTailCacheControl, buildAnthropicCacheControl, buildBedrockCachePoint, cloneMessage, resolvePromptCacheTtl, stripAnthropicCacheControl, stripBedrockCacheControl };
 
 //# sourceMappingURL=cache.mjs.map