@librechat/agents 3.1.74 → 3.1.75

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

@@ -1 +1 @@
-{"version":3,"file":"cache.mjs","sources":["../../../src/messages/cache.ts"],"sourcesContent":["import {\n  AIMessage,\n  BaseMessage,\n  ToolMessage,\n  HumanMessage,\n  SystemMessage,\n  MessageContentComplex,\n} from '@langchain/core/messages';\nimport type { AnthropicMessage } from '@/types/messages';\nimport type Anthropic from '@anthropic-ai/sdk';\nimport { ContentTypes } from '@/common/enum';\n\ntype MessageWithContent = {\n  content?: string | MessageContentComplex[];\n};\n\n/**\n * Deep clones a message's content to prevent mutation of the original.\n */\nfunction deepCloneContent<T extends string | MessageContentComplex[]>(\n  content: T\n): T {\n  if (typeof content === 'string') {\n    return content;\n  }\n  if (Array.isArray(content)) {\n    return content.map((block) => ({ ...block })) as T;\n  }\n  return content;\n}\n\n/**\n * Clones a message with new content. For LangChain BaseMessage instances,\n * constructs a proper class instance so that `instanceof` checks are preserved\n * in downstream code (e.g., ensureThinkingBlockInMessages).\n * For plain objects (AnthropicMessage), uses object spread.\n */\nfunction cloneMessage<T extends MessageWithContent>(\n  message: T,\n  content: string | MessageContentComplex[]\n): T {\n  if (message instanceof BaseMessage) {\n    const baseParams = {\n      content,\n      additional_kwargs: { ...message.additional_kwargs },\n      response_metadata: { ...message.response_metadata },\n      id: message.id,\n      name: message.name,\n    };\n\n    const msgType = message.getType();\n    switch (msgType) {\n    case 'ai':\n      return new AIMessage({\n        ...baseParams,\n        tool_calls: (message as unknown as AIMessage).tool_calls,\n      }) as unknown as T;\n    case 'human':\n      return new HumanMessage(baseParams) as unknown as T;\n    case 'system':\n      return new SystemMessage(baseParams) as unknown as T;\n    case 'tool':\n      return new ToolMessage({\n        ...baseParams,\n        tool_call_id: (message as unknown as ToolMessage).tool_call_id,\n      }) as unknown as T;\n    default:\n      break;\n    }\n  }\n\n  const {\n    lc_kwargs: _lc_kwargs,\n    lc_serializable: _lc_serializable,\n    lc_namespace: _lc_namespace,\n    ...rest\n  } = message as T & {\n    lc_kwargs?: unknown;\n    lc_serializable?: unknown;\n    lc_namespace?: unknown;\n  };\n\n  const cloned = { ...rest, content } as T;\n\n  // LangChain messages don't have a direct 'role' property - derive it from getType()\n  if (\n    'getType' in message &&\n    typeof message.getType === 'function' &&\n    !('role' in cloned)\n  ) {\n    const msgType = (message as unknown as BaseMessage).getType();\n    const roleMap: Record<string, string> = {\n      human: 'user',\n      ai: 'assistant',\n      system: 'system',\n      tool: 'tool',\n    };\n    (cloned as Record<string, unknown>).role = roleMap[msgType] || msgType;\n  }\n\n  return cloned;\n}\n\n/**\n * Anthropic API: Adds cache control to the appropriate user messages in the payload.\n * Strips ALL existing cache control (both Anthropic and Bedrock formats) from all messages,\n * then adds fresh cache control to the last 2 user messages in a single backward pass.\n * This ensures we don't accumulate stale cache points across multiple turns.\n * Returns a new array - only clones messages that require modification.\n * @param messages - The array of message objects.\n * @returns - A new array of message objects with cache control added.\n */\nexport function addCacheControl<T extends AnthropicMessage | BaseMessage>(\n  messages: T[]\n): T[] {\n  if (!Array.isArray(messages) || messages.length < 2) {\n    return messages;\n  }\n\n  const updatedMessages: T[] = [...messages];\n  let userMessagesModified = 0;\n\n  for (let i = updatedMessages.length - 1; i >= 0; i--) {\n    const originalMessage = updatedMessages[i];\n    const content = originalMessage.content;\n    const isUserMessage =\n      ('getType' in originalMessage && originalMessage.getType() === 'human') ||\n      ('role' in originalMessage && originalMessage.role === 'user');\n    const hasArrayContent = Array.isArray(content);\n    const needsCacheAdd =\n      userMessagesModified < 2 &&\n      isUserMessage &&\n      (typeof content === 'string' || hasArrayContent);\n\n    // Skip messages that don't need any work\n    if (!needsCacheAdd && !hasArrayContent) {\n      continue;\n    }\n\n    let workingContent: MessageContentComplex[];\n    let modified = false;\n\n    if (hasArrayContent) {\n      // Single pass: clone blocks, strip cache markers and cache points,\n      // find last text block index for cache insertion — all at once.\n      const src = content as MessageContentComplex[];\n      workingContent = [];\n      let lastTextIndex = -1;\n      for (let j = 0; j < src.length; j++) {\n        const block = src[j];\n        if (isCachePoint(block)) {\n          modified = true;\n          continue; // skip cache point blocks\n        }\n        const cloned = { ...block };\n        if ('cache_control' in cloned) {\n          delete (cloned as Record<string, unknown>).cache_control;\n          modified = true;\n        }\n        if ('type' in cloned && cloned.type === 'text') {\n          lastTextIndex = workingContent.length;\n        }\n        workingContent.push(cloned as MessageContentComplex);\n      }\n\n      if (!modified && !needsCacheAdd) {\n        continue; // nothing to strip and no cache to add\n      }\n\n      // Add cache control to the last text block for user messages\n      if (needsCacheAdd && lastTextIndex >= 0) {\n        (\n          workingContent[lastTextIndex] as Anthropic.TextBlockParam\n        ).cache_control = {\n          type: 'ephemeral',\n        };\n        userMessagesModified++;\n      }\n    } else if (typeof content === 'string' && needsCacheAdd) {\n      workingContent = [\n        { type: 'text', text: content, cache_control: { type: 'ephemeral' } },\n      ] as unknown as MessageContentComplex[];\n      userMessagesModified++;\n    } else {\n      continue;\n    }\n\n    updatedMessages[i] = cloneMessage(\n      originalMessage as MessageWithContent,\n      workingContent\n    ) as T;\n  }\n\n  return updatedMessages;\n}\n\n/**\n * Checks if a content block is a cache point\n */\nfunction isCachePoint(block: MessageContentComplex): boolean {\n  return 'cachePoint' in block && !('type' in block);\n}\n\n/**\n * Checks if a message's content has Anthropic cache_control fields.\n */\nfunction hasAnthropicCacheControl(content: MessageContentComplex[]): boolean {\n  for (let i = 0; i < content.length; i++) {\n    if ('cache_control' in content[i]) return true;\n  }\n  return false;\n}\n\n/**\n * Removes all Anthropic cache_control fields from messages\n * Used when switching from Anthropic to Bedrock provider\n * Returns a new array - only clones messages that require modification.\n */\nexport function stripAnthropicCacheControl<T extends MessageWithContent>(\n  messages: T[]\n): T[] {\n  if (!Array.isArray(messages)) {\n    return messages;\n  }\n\n  const updatedMessages: T[] = [...messages];\n\n  for (let i = 0; i < updatedMessages.length; i++) {\n    const originalMessage = updatedMessages[i];\n    const content = originalMessage.content;\n\n    if (!Array.isArray(content) || !hasAnthropicCacheControl(content)) {\n      continue;\n    }\n\n    const clonedContent = deepCloneContent(content);\n    for (let j = 0; j < clonedContent.length; j++) {\n      const block = clonedContent[j] as Record<string, unknown>;\n      if ('cache_control' in block) {\n        delete block.cache_control;\n      }\n    }\n    updatedMessages[i] = cloneMessage(originalMessage, clonedContent);\n  }\n\n  return updatedMessages;\n}\n\n/**\n * Checks if a message's content has Bedrock cachePoint blocks.\n */\nfunction hasBedrockCachePoint(content: MessageContentComplex[]): boolean {\n  for (let i = 0; i < content.length; i++) {\n    if (isCachePoint(content[i])) return true;\n  }\n  return false;\n}\n\n/**\n * Removes all Bedrock cachePoint blocks from messages\n * Used when switching from Bedrock to Anthropic provider\n * Returns a new array - only clones messages that require modification.\n */\nexport function stripBedrockCacheControl<T extends MessageWithContent>(\n  messages: T[]\n): T[] {\n  if (!Array.isArray(messages)) {\n    return messages;\n  }\n\n  const updatedMessages: T[] = [...messages];\n\n  for (let i = 0; i < updatedMessages.length; i++) {\n    const originalMessage = updatedMessages[i];\n    const content = originalMessage.content;\n\n    if (!Array.isArray(content) || !hasBedrockCachePoint(content)) {\n      continue;\n    }\n\n    const clonedContent = deepCloneContent(content).filter(\n      (block) => !isCachePoint(block as MessageContentComplex)\n    );\n    updatedMessages[i] = cloneMessage(originalMessage, clonedContent);\n  }\n\n  return updatedMessages;\n}\n\n/**\n * Adds Bedrock Converse API cache points to the last two messages.\n * Inserts `{ cachePoint: { type: 'default' } }` as a separate content block\n * immediately after the last text block in each targeted message.\n * Strips ALL existing cache control (both Bedrock and Anthropic formats) from all messages,\n * then adds fresh cache points to the last 2 messages in a single backward pass.\n * This ensures we don't accumulate stale cache points across multiple turns.\n * Returns a new array - only clones messages that require modification.\n * @param messages - The array of message objects.\n * @returns - A new array of message objects with cache points added.\n */\nexport function addBedrockCacheControl<\n  T extends Partial<BaseMessage> & MessageWithContent,\n>(messages: T[]): T[] {\n  if (!Array.isArray(messages) || messages.length < 2) {\n    return messages;\n  }\n\n  const updatedMessages: T[] = [...messages];\n  let messagesModified = 0;\n\n  for (let i = updatedMessages.length - 1; i >= 0; i--) {\n    const originalMessage = updatedMessages[i];\n    const isToolMessage =\n      'getType' in originalMessage &&\n      typeof originalMessage.getType === 'function' &&\n      originalMessage.getType() === 'tool';\n\n    const content = originalMessage.content;\n    const hasArrayContent = Array.isArray(content);\n    const isEmptyString = typeof content === 'string' && content === '';\n    const needsCacheAdd =\n      messagesModified < 2 &&\n      !isToolMessage &&\n      !isEmptyString &&\n      (typeof content === 'string' || hasArrayContent);\n\n    if (!needsCacheAdd && !hasArrayContent) {\n      continue;\n    }\n\n    let workingContent: MessageContentComplex[];\n    let modified = false;\n\n    if (hasArrayContent) {\n      // Single pass: clone blocks, strip cache markers, find last\n      // non-empty text block for cache point insertion — all at once.\n      const src = content as MessageContentComplex[];\n      workingContent = [];\n      let lastNonEmptyTextIndex = -1;\n      for (let j = 0; j < src.length; j++) {\n        const block = src[j];\n        if (isCachePoint(block)) {\n          modified = true;\n          continue;\n        }\n        const cloned = { ...block };\n        if ('cache_control' in cloned) {\n          delete (cloned as Record<string, unknown>).cache_control;\n          modified = true;\n        }\n        const type = (cloned as { type?: string }).type;\n        if (type === ContentTypes.TEXT || type === 'text') {\n          const text = (cloned as { text?: string }).text;\n          if (text != null && text.trim() !== '') {\n            lastNonEmptyTextIndex = workingContent.length;\n          }\n        }\n        workingContent.push(cloned as MessageContentComplex);\n      }\n\n      if (!modified && !needsCacheAdd) {\n        continue;\n      }\n\n      // Insert cache point after the last non-empty text block.\n      // Skip if no cacheable text content exists (whitespace-only messages).\n      if (needsCacheAdd && lastNonEmptyTextIndex >= 0) {\n        workingContent.splice(lastNonEmptyTextIndex + 1, 0, {\n          cachePoint: { type: 'default' },\n        } as MessageContentComplex);\n        messagesModified++;\n      }\n    } else if (typeof content === 'string' && needsCacheAdd) {\n      workingContent = [\n        { type: ContentTypes.TEXT, text: content },\n        { cachePoint: { type: 'default' } } as MessageContentComplex,\n      ];\n      messagesModified++;\n    } else {\n      continue;\n    }\n\n    updatedMessages[i] = cloneMessage(originalMessage, workingContent);\n  }\n\n  return updatedMessages;\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"cache.mjs","sources":["../../../src/messages/cache.ts"],"sourcesContent":["import {\n  AIMessage,\n  BaseMessage,\n  ToolMessage,\n  HumanMessage,\n  SystemMessage,\n  MessageContentComplex,\n} from '@langchain/core/messages';\nimport type { AnthropicMessage } from '@/types/messages';\nimport type Anthropic from '@anthropic-ai/sdk';\nimport { ContentTypes } from '@/common/enum';\n\ntype MessageWithContent = {\n  content?: string | MessageContentComplex[];\n};\n\ntype MessageContentWithCacheControl = MessageContentComplex & {\n  cache_control?: unknown;\n};\n\n/**\n * Deep clones a message's content to prevent mutation of the original.\n */\nfunction deepCloneContent<T extends string | MessageContentComplex[]>(\n  content: T\n): T {\n  if (typeof content === 'string') {\n    return content;\n  }\n  if (Array.isArray(content)) {\n    return content.map((block) => ({ ...block })) as T;\n  }\n  return content;\n}\n\n/**\n * Clones a message with new content. For LangChain BaseMessage instances,\n * constructs a proper class instance so that `instanceof` checks are preserved\n * in downstream code (e.g., ensureThinkingBlockInMessages).\n * For plain objects (AnthropicMessage), uses object spread.\n */\nfunction cloneMessage<T extends MessageWithContent>(\n  message: T,\n  content: string | MessageContentComplex[]\n): T {\n  if (message instanceof BaseMessage) {\n    const baseParams = {\n      content,\n      additional_kwargs: { ...message.additional_kwargs },\n      response_metadata: { ...message.response_metadata },\n      id: message.id,\n      name: message.name,\n    };\n\n    const msgType = message.getType();\n    switch (msgType) {\n    case 'ai':\n      return new AIMessage({\n        ...baseParams,\n        tool_calls: (message as unknown as AIMessage).tool_calls,\n      }) as unknown as T;\n    case 'human':\n      return new HumanMessage(baseParams) as unknown as T;\n    case 'system':\n      return new SystemMessage(baseParams) as unknown as T;\n    case 'tool':\n      return new ToolMessage({\n        ...baseParams,\n        tool_call_id: (message as unknown as ToolMessage).tool_call_id,\n      }) as unknown as T;\n    default:\n      break;\n    }\n  }\n\n  const {\n    lc_kwargs: _lc_kwargs,\n    lc_serializable: _lc_serializable,\n    lc_namespace: _lc_namespace,\n    ...rest\n  } = message as T & {\n    lc_kwargs?: unknown;\n    lc_serializable?: unknown;\n    lc_namespace?: unknown;\n  };\n\n  const cloned = { ...rest, content } as T;\n\n  // LangChain messages don't have a direct 'role' property - derive it from getType()\n  if (\n    'getType' in message &&\n    typeof message.getType === 'function' &&\n    !('role' in cloned)\n  ) {\n    const msgType = (message as unknown as BaseMessage).getType();\n    const roleMap: Record<string, string> = {\n      human: 'user',\n      ai: 'assistant',\n      system: 'system',\n      tool: 'tool',\n    };\n    (cloned as Record<string, unknown>).role = roleMap[msgType] || msgType;\n  }\n\n  return cloned;\n}\n\nfunction stripAnthropicCacheControlFromBlocks(\n  content: MessageContentComplex[]\n): { content: MessageContentComplex[]; modified: boolean } {\n  let modified = false;\n  const strippedContent = content.map((block) => {\n    if (!('cache_control' in block)) {\n      return block;\n    }\n\n    const cloned: MessageContentWithCacheControl = { ...block };\n    delete cloned.cache_control;\n    modified = true;\n    return cloned;\n  });\n\n  return { content: strippedContent, modified };\n}\n\nfunction sanitizeBedrockSystemMessage<T extends MessageWithContent>(\n  message: T\n): T {\n  const content = message.content;\n  if (!Array.isArray(content)) {\n    return message;\n  }\n\n  const stripped = stripAnthropicCacheControlFromBlocks(content);\n  if (!stripped.modified) {\n    return message;\n  }\n\n  return cloneMessage(message, stripped.content);\n}\n\n/**\n * Anthropic API: Adds cache control to the appropriate user messages in the payload.\n * Strips ALL existing cache control (both Anthropic and Bedrock formats) from all messages,\n * then adds fresh cache control to the last 2 user messages in a single backward pass.\n * This ensures we don't accumulate stale cache points across multiple turns.\n * Returns a new array - only clones messages that require modification.\n * @param messages - The array of message objects.\n * @returns - A new array of message objects with cache control added.\n */\nexport function addCacheControl<T extends AnthropicMessage | BaseMessage>(\n  messages: T[]\n): T[] {\n  if (!Array.isArray(messages) || messages.length < 2) {\n    return messages;\n  }\n\n  const updatedMessages: T[] = [...messages];\n  let userMessagesModified = 0;\n\n  for (let i = updatedMessages.length - 1; i >= 0; i--) {\n    const originalMessage = updatedMessages[i];\n    const content = originalMessage.content;\n    const isUserMessage =\n      ('getType' in originalMessage && originalMessage.getType() === 'human') ||\n      ('role' in originalMessage && originalMessage.role === 'user');\n    const hasArrayContent = Array.isArray(content);\n    const needsCacheAdd =\n      userMessagesModified < 2 &&\n      isUserMessage &&\n      (typeof content === 'string' || hasArrayContent);\n\n    // Skip messages that don't need any work\n    if (!needsCacheAdd && !hasArrayContent) {\n      continue;\n    }\n\n    let workingContent: MessageContentComplex[];\n    let modified = false;\n\n    if (hasArrayContent) {\n      // Single pass: clone blocks, strip cache markers and cache points,\n      // find last text block index for cache insertion — all at once.\n      const src = content as MessageContentComplex[];\n      workingContent = [];\n      let lastTextIndex = -1;\n      for (let j = 0; j < src.length; j++) {\n        const block = src[j];\n        if (isCachePoint(block)) {\n          modified = true;\n          continue; // skip cache point blocks\n        }\n        const cloned = { ...block };\n        if ('cache_control' in cloned) {\n          delete (cloned as Record<string, unknown>).cache_control;\n          modified = true;\n        }\n        if ('type' in cloned && cloned.type === 'text') {\n          lastTextIndex = workingContent.length;\n        }\n        workingContent.push(cloned as MessageContentComplex);\n      }\n\n      if (!modified && !needsCacheAdd) {\n        continue; // nothing to strip and no cache to add\n      }\n\n      // Add cache control to the last text block for user messages\n      if (needsCacheAdd && lastTextIndex >= 0) {\n        (\n          workingContent[lastTextIndex] as Anthropic.TextBlockParam\n        ).cache_control = {\n          type: 'ephemeral',\n        };\n        userMessagesModified++;\n      }\n    } else if (typeof content === 'string' && needsCacheAdd) {\n      workingContent = [\n        { type: 'text', text: content, cache_control: { type: 'ephemeral' } },\n      ] as unknown as MessageContentComplex[];\n      userMessagesModified++;\n    } else {\n      continue;\n    }\n\n    updatedMessages[i] = cloneMessage(\n      originalMessage as MessageWithContent,\n      workingContent\n    ) as T;\n  }\n\n  return updatedMessages;\n}\n\n/**\n * Checks if a content block is a cache point\n */\nfunction isCachePoint(block: MessageContentComplex): boolean {\n  return 'cachePoint' in block && !('type' in block);\n}\n\n/**\n * Checks if a message's content has Anthropic cache_control fields.\n */\nfunction hasAnthropicCacheControl(content: MessageContentComplex[]): boolean {\n  for (let i = 0; i < content.length; i++) {\n    if ('cache_control' in content[i]) return true;\n  }\n  return false;\n}\n\n/**\n * Removes all Anthropic cache_control fields from messages\n * Used when switching from Anthropic to Bedrock provider\n * Returns a new array - only clones messages that require modification.\n */\nexport function stripAnthropicCacheControl<T extends MessageWithContent>(\n  messages: T[]\n): T[] {\n  if (!Array.isArray(messages)) {\n    return messages;\n  }\n\n  const updatedMessages: T[] = [...messages];\n\n  for (let i = 0; i < updatedMessages.length; i++) {\n    const originalMessage = updatedMessages[i];\n    const content = originalMessage.content;\n\n    if (!Array.isArray(content) || !hasAnthropicCacheControl(content)) {\n      continue;\n    }\n\n    const clonedContent = deepCloneContent(content);\n    for (let j = 0; j < clonedContent.length; j++) {\n      const block = clonedContent[j] as Record<string, unknown>;\n      if ('cache_control' in block) {\n        delete block.cache_control;\n      }\n    }\n    updatedMessages[i] = cloneMessage(originalMessage, clonedContent);\n  }\n\n  return updatedMessages;\n}\n\n/**\n * Checks if a message's content has Bedrock cachePoint blocks.\n */\nfunction hasBedrockCachePoint(content: MessageContentComplex[]): boolean {\n  for (let i = 0; i < content.length; i++) {\n    if (isCachePoint(content[i])) return true;\n  }\n  return false;\n}\n\n/**\n * Removes all Bedrock cachePoint blocks from messages\n * Used when switching from Bedrock to Anthropic provider\n * Returns a new array - only clones messages that require modification.\n */\nexport function stripBedrockCacheControl<T extends MessageWithContent>(\n  messages: T[]\n): T[] {\n  if (!Array.isArray(messages)) {\n    return messages;\n  }\n\n  const updatedMessages: T[] = [...messages];\n\n  for (let i = 0; i < updatedMessages.length; i++) {\n    const originalMessage = updatedMessages[i];\n    const content = originalMessage.content;\n\n    if (!Array.isArray(content) || !hasBedrockCachePoint(content)) {\n      continue;\n    }\n\n    const clonedContent = deepCloneContent(content).filter(\n      (block) => !isCachePoint(block as MessageContentComplex)\n    );\n    updatedMessages[i] = cloneMessage(originalMessage, clonedContent);\n  }\n\n  return updatedMessages;\n}\n\n/**\n * Adds Bedrock Converse API cache points to the last two messages.\n * Inserts `{ cachePoint: { type: 'default' } }` as a separate content block\n * immediately after the last text block in each targeted message.\n * Strips ALL existing cache control (both Bedrock and Anthropic formats) from all messages,\n * then adds fresh cache points to the last 2 messages in a single backward pass.\n * This ensures we don't accumulate stale cache points across multiple turns.\n * Returns a new array - only clones messages that require modification.\n * @param messages - The array of message objects.\n * @returns - A new array of message objects with cache points added.\n */\nexport function addBedrockCacheControl<\n  T extends Partial<BaseMessage> & MessageWithContent,\n>(messages: T[]): T[] {\n  if (!Array.isArray(messages) || messages.length < 2) {\n    return messages;\n  }\n\n  const updatedMessages: T[] = [...messages];\n  let messagesModified = 0;\n\n  for (let i = updatedMessages.length - 1; i >= 0; i--) {\n    const originalMessage = updatedMessages[i];\n    const messageType =\n      'getType' in originalMessage &&\n      typeof originalMessage.getType === 'function'\n        ? originalMessage.getType()\n        : undefined;\n    const messageRole =\n      'role' in originalMessage && typeof originalMessage.role === 'string'\n        ? originalMessage.role\n        : undefined;\n\n    const isSystemMessage =\n      messageType === 'system' || messageRole === 'system';\n    if (isSystemMessage) {\n      updatedMessages[i] = sanitizeBedrockSystemMessage(originalMessage);\n      continue;\n    }\n\n    const isToolMessage = messageType === 'tool' || messageRole === 'tool';\n    const content = originalMessage.content;\n    const hasArrayContent = Array.isArray(content);\n    const isEmptyString = typeof content === 'string' && content === '';\n    const needsCacheAdd =\n      messagesModified < 2 &&\n      !isToolMessage &&\n      !isEmptyString &&\n      (typeof content === 'string' || hasArrayContent);\n\n    if (!needsCacheAdd && !hasArrayContent) {\n      continue;\n    }\n\n    let workingContent: MessageContentComplex[];\n    let modified = false;\n\n    if (hasArrayContent) {\n      // Single pass: clone blocks, strip cache markers, find last\n      // non-empty text block for cache point insertion — all at once.\n      const src = content as MessageContentComplex[];\n      workingContent = [];\n      let lastNonEmptyTextIndex = -1;\n      for (let j = 0; j < src.length; j++) {\n        const block = src[j];\n        if (isCachePoint(block)) {\n          modified = true;\n          continue;\n        }\n        const cloned = { ...block };\n        if ('cache_control' in cloned) {\n          delete (cloned as Record<string, unknown>).cache_control;\n          modified = true;\n        }\n        const type = (cloned as { type?: string }).type;\n        if (type === ContentTypes.TEXT || type === 'text') {\n          const text = (cloned as { text?: string }).text;\n          if (text != null && text.trim() !== '') {\n            lastNonEmptyTextIndex = workingContent.length;\n          }\n        }\n        workingContent.push(cloned as MessageContentComplex);\n      }\n\n      if (!modified && !needsCacheAdd) {\n        continue;\n      }\n\n      // Insert cache point after the last non-empty text block.\n      // Skip if no cacheable text content exists (whitespace-only messages).\n      if (needsCacheAdd && lastNonEmptyTextIndex >= 0) {\n        workingContent.splice(lastNonEmptyTextIndex + 1, 0, {\n          cachePoint: { type: 'default' },\n        } as MessageContentComplex);\n        messagesModified++;\n      }\n    } else if (typeof content === 'string' && needsCacheAdd) {\n      workingContent = [\n        { type: ContentTypes.TEXT, text: content },\n        { cachePoint: { type: 'default' } } as MessageContentComplex,\n      ];\n      messagesModified++;\n    } else {\n      continue;\n    }\n\n    updatedMessages[i] = cloneMessage(originalMessage, workingContent);\n  }\n\n  return updatedMessages;\n}\n"],"names":[],"mappings":"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"}

package/dist/types/agents/AgentContext.d.ts

@@ -126,7 +126,7 @@ export declare class AgentContext {
     private summaryTokenCount;
     /**
      * Where the summary should be injected:
-     * - `'system_prompt'`: cross-run summary, included in `buildInstructionsString`
+     * - `'system_prompt'`: cross-run summary, included in the dynamic system tail
      * - `'user_message'`: mid-run compaction, injected as HumanMessage on clean slate
      * - `'none'`: no summary present
      */
@@ -193,7 +193,8 @@ export declare class AgentContext {
     private buildProgrammaticOnlyToolsInstructions;
     /**
      * Gets the system runnable, creating it lazily if needed.
-     * Includes instructions, additional instructions, and programmatic-only tools documentation.
+     * Includes stable instructions, dynamic additional instructions, and
+     * programmatic-only tools documentation.
      * Only rebuilds when marked stale (via markToolsAsDiscovered).
      */
     get systemRunnable(): Runnable<BaseMessage[], (BaseMessage | SystemMessage)[], RunnableConfig<Record<string, unknown>>> | undefined;
@@ -203,10 +204,16 @@ export declare class AgentContext {
      */
     initializeSystemRunnable(): void;
     /**
-     * Builds the raw instructions string (without creating SystemMessage).
+     * Builds the cacheable instructions string (without creating SystemMessage).
      * Includes agent identity preamble and handoff context when available.
      */
-    private buildInstructionsString;
+    private buildStableInstructionsString;
+    /**
+     * Builds the dynamic system-tail string (without creating SystemMessage).
+     * Keep this out of prompt-cache-marked content so volatile context does not
+     * invalidate the stable prefix.
+     */
+    private buildDynamicInstructionsString;
     /**
      * Builds the agent identity preamble including handoff context if present.
      * This helps the agent understand its role in the multi-agent workflow.
@@ -217,6 +224,9 @@ export declare class AgentContext {
      * Only called when content has actually changed.
      */
     private buildSystemRunnable;
+    private hasAnthropicPromptCache;
+    private hasBedrockPromptCache;
+    private buildSystemMessage;
     /**
      * Reset context for a new run
      */

package/dist/types/agents/__tests__/promptCacheLiveHelpers.d.ts

@@ -0,0 +1,46 @@
+import type { UsageMetadata } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { Providers } from '@/common';
+type LivePromptCacheProvider = Providers.ANTHROPIC | Providers.BEDROCK;
+type PromptCacheExpectedSystemBlock = {
+    type: 'text';
+    text: string;
+    cache_control?: {
+        type: 'ephemeral';
+    };
+} | {
+    cachePoint: {
+        type: 'default';
+    };
+};
+type LivePromptCacheClientOptions = t.ClientOptions | t.BedrockAnthropicClientOptions;
+export declare function buildStableInstructions({ nonce, providerLabel, }: {
+    nonce: string;
+    providerLabel: string;
+}): string;
+export declare function buildDynamicInstructions({ marker, tailDescription, }: {
+    marker: string;
+    tailDescription: string;
+}): string;
+export declare function waitForCachePropagation(): Promise<void>;
+export declare function assertSystemPayloadShape({ agentId, provider, clientOptions, stableInstructions, dynamicInstructions, expectedContent, }: {
+    agentId: string;
+    provider: LivePromptCacheProvider;
+    clientOptions: LivePromptCacheClientOptions;
+    stableInstructions: string;
+    dynamicInstructions: string;
+    expectedContent: PromptCacheExpectedSystemBlock[];
+}): Promise<void>;
+export declare function runLiveTurn({ provider, providerLabel, clientOptions, runId, threadId, stableInstructions, dynamicInstructions, }: {
+    provider: LivePromptCacheProvider;
+    providerLabel: string;
+    clientOptions: LivePromptCacheClientOptions;
+    runId: string;
+    threadId: string;
+    stableInstructions: string;
+    dynamicInstructions: string;
+}): Promise<{
+    text: string;
+    usage: UsageMetadata;
+}>;
+export {};

package/dist/types/types/graph.d.ts

@@ -311,10 +311,12 @@ export interface AgentInputs {
     toolMap?: ToolMap;
     tools?: GraphTools;
     provider: Providers;
+    /** Stable/cacheable system instructions. */
     instructions?: string;
     streamBuffer?: number;
     maxContextTokens?: number;
     clientOptions?: ClientOptions;
+    /** Dynamic system tail appended after stable instructions without provider cache markers. */
     additional_instructions?: string;
     reasoningKey?: 'reasoning_content' | 'reasoning';
     /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */
@@ -340,7 +342,7 @@ export interface AgentInputs {
     summarizationEnabled?: boolean;
     summarizationConfig?: SummarizationConfig;
     /** Cross-run summary from a previous run, forwarded from formatAgentMessages.
-     *  Injected into the system message via AgentContext.buildInstructionsString(). */
+     *  Injected into the dynamic system tail via AgentContext. */
     initialSummary?: {
         text: string;
         tokenCount: number;

package/dist/types/types/run.d.ts

@@ -63,7 +63,9 @@ export interface AgentStateChannels {
     messages: BaseMessage[];
     next: string;
     [key: string]: unknown;
+    /** Stable/cacheable system instructions. */
     instructions?: string;
+    /** Dynamic system tail appended after stable instructions. */
     additional_instructions?: string;
 }
 export interface Member {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.74",
+  "version": "3.1.75",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/agents/AgentContext.ts

@@ -20,6 +20,16 @@ import { addCacheControl } from '@/messages/cache';
 import { DEFAULT_RESERVE_RATIO } from '@/messages';
 import { toJsonSchema } from '@/utils/schema';
 
+type AgentSystemTextBlock = {
+  type: 'text';
+  text: string;
+  cache_control?: { type: 'ephemeral' };
+};
+
+type AgentSystemContentBlock =
+  | AgentSystemTextBlock
+  | { cachePoint: { type: 'default' } };
+
 /**
  * Encapsulates agent-specific state that can vary between agents in a multi-agent system
  */
@@ -249,7 +259,7 @@ export class AgentContext {
   private summaryTokenCount: number = 0;
   /**
    * Where the summary should be injected:
-   * - `'system_prompt'`: cross-run summary, included in `buildInstructionsString`
+   * - `'system_prompt'`: cross-run summary, included in the dynamic system tail
    * - `'user_message'`: mid-run compaction, injected as HumanMessage on clean slate
    * - `'none'`: no summary present
    */
@@ -417,7 +427,8 @@ export class AgentContext {
 
   /**
    * Gets the system runnable, creating it lazily if needed.
-   * Includes instructions, additional instructions, and programmatic-only tools documentation.
+   * Includes stable instructions, dynamic additional instructions, and
+   * programmatic-only tools documentation.
    * Only rebuilds when marked stale (via markToolsAsDiscovered).
    */
   get systemRunnable():
@@ -431,8 +442,10 @@ export class AgentContext {
       return this.cachedSystemRunnable;
     }
 
-    const instructionsString = this.buildInstructionsString();
-    this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
+    this.cachedSystemRunnable = this.buildSystemRunnable({
+      stableInstructions: this.buildStableInstructionsString(),
+      dynamicInstructions: this.buildDynamicInstructionsString(),
+    });
     this.systemRunnableStale = false;
     return this.cachedSystemRunnable;
   }
@@ -443,17 +456,19 @@ export class AgentContext {
    */
   initializeSystemRunnable(): void {
     if (this.systemRunnableStale || this.cachedSystemRunnable === undefined) {
-      const instructionsString = this.buildInstructionsString();
-      this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
+      this.cachedSystemRunnable = this.buildSystemRunnable({
+        stableInstructions: this.buildStableInstructionsString(),
+        dynamicInstructions: this.buildDynamicInstructionsString(),
+      });
       this.systemRunnableStale = false;
     }
   }
 
   /**
-   * Builds the raw instructions string (without creating SystemMessage).
+   * Builds the cacheable instructions string (without creating SystemMessage).
    * Includes agent identity preamble and handoff context when available.
    */
-  private buildInstructionsString(): string {
+  private buildStableInstructionsString(): string {
     const parts: string[] = [];
 
     const identityPreamble = this.buildIdentityPreamble();
@@ -465,6 +480,22 @@ export class AgentContext {
       parts.push(this.instructions);
     }
 
+    const programmaticToolsDoc = this.buildProgrammaticOnlyToolsInstructions();
+    if (programmaticToolsDoc) {
+      parts.push(programmaticToolsDoc);
+    }
+
+    return parts.join('\n\n');
+  }
+
+  /**
+   * Builds the dynamic system-tail string (without creating SystemMessage).
+   * Keep this out of prompt-cache-marked content so volatile context does not
+   * invalidate the stable prefix.
+   */
+  private buildDynamicInstructionsString(): string {
+    const parts: string[] = [];
+
     if (
       this.additionalInstructions != null &&
       this.additionalInstructions !== ''
@@ -472,14 +503,10 @@ export class AgentContext {
       parts.push(this.additionalInstructions);
     }
 
-    const programmaticToolsDoc = this.buildProgrammaticOnlyToolsInstructions();
-    if (programmaticToolsDoc) {
-      parts.push(programmaticToolsDoc);
-    }
-
-    // Cross-run summary: include in system prompt so the model has context
-    // from the prior run.  Mid-run summaries are injected as a HumanMessage
-    // on the post-compaction clean slate instead (see buildSystemRunnable).
+    // Cross-run summary: include in the system tail so the model has context
+    // from the prior run without invalidating the cacheable prefix. Mid-run
+    // summaries are injected as a HumanMessage on the post-compaction clean
+    // slate instead (see buildSystemRunnable).
     if (
       this._summaryLocation === 'system_prompt' &&
       this.summaryText != null &&
@@ -523,9 +550,13 @@ export class AgentContext {
    * Build system runnable from pre-built instructions string.
    * Only called when content has actually changed.
    */
-  private buildSystemRunnable(
-    instructionsString: string
-  ):
+  private buildSystemRunnable({
+    stableInstructions,
+    dynamicInstructions,
+  }: {
+    stableInstructions: string;
+    dynamicInstructions: string;
+  }):
     | Runnable<
         BaseMessage[],
         (BaseMessage | SystemMessage)[],
@@ -537,35 +568,17 @@ export class AgentContext {
       this.summaryText != null &&
       this.summaryText !== '';
 
-    if (!instructionsString && !hasMidRunSummary) {
+    if (!stableInstructions && !dynamicInstructions && !hasMidRunSummary) {
       this.systemMessageTokens = 0;
       return undefined;
     }
 
-    let finalInstructions: string | BaseMessageFields = instructionsString;
-
-    let usePromptCache = false;
-    if (this.provider === Providers.ANTHROPIC) {
-      const anthropicOptions = this.clientOptions as
-        | t.AnthropicClientOptions
-        | undefined;
-      if (anthropicOptions?.promptCache === true) {
-        usePromptCache = true;
-        finalInstructions = {
-          content: [
-            {
-              type: 'text',
-              text: instructionsString,
-              cache_control: { type: 'ephemeral' },
-            },
-          ],
-        };
-      }
-    }
-
-    const systemMessage = instructionsString
-      ? new SystemMessage(finalInstructions)
-      : undefined;
+    const usePromptCache = this.hasAnthropicPromptCache();
+    const systemMessage = this.buildSystemMessage({
+      stableInstructions,
+      dynamicInstructions,
+      usePromptCache,
+    });
 
     if (this.tokenCounter) {
       this.systemMessageTokens = systemMessage
@@ -615,6 +628,72 @@ export class AgentContext {
     }).withConfig({ runName: 'prompt' });
   }
 
+  private hasAnthropicPromptCache(): boolean {
+    if (this.provider !== Providers.ANTHROPIC) {
+      return false;
+    }
+    const anthropicOptions = this.clientOptions as
+      | t.AnthropicClientOptions
+      | undefined;
+    return anthropicOptions?.promptCache === true;
+  }
+
+  private hasBedrockPromptCache(): boolean {
+    if (this.provider !== Providers.BEDROCK) {
+      return false;
+    }
+    const bedrockOptions = this.clientOptions as
+      | t.BedrockAnthropicClientOptions
+      | undefined;
+    return bedrockOptions?.promptCache === true;
+  }
+
+  private buildSystemMessage({
+    stableInstructions,
+    dynamicInstructions,
+    usePromptCache,
+  }: {
+    stableInstructions: string;
+    dynamicInstructions: string;
+    usePromptCache: boolean;
+  }): SystemMessage | undefined {
+    if (!stableInstructions && !dynamicInstructions) {
+      return undefined;
+    }
+
+    if (usePromptCache) {
+      const content: AgentSystemContentBlock[] = [];
+      if (stableInstructions) {
+        content.push({
+          type: 'text',
+          text: stableInstructions,
+          cache_control: { type: 'ephemeral' },
+        });
+      }
+      if (dynamicInstructions) {
+        content.push({ type: 'text', text: dynamicInstructions });
+      }
+      return new SystemMessage({ content } as BaseMessageFields);
+    }
+
+    if (this.hasBedrockPromptCache() && stableInstructions) {
+      const content: AgentSystemContentBlock[] = [
+        { type: 'text', text: stableInstructions },
+        { cachePoint: { type: 'default' } },
+      ];
+      if (dynamicInstructions) {
+        content.push({ type: 'text', text: dynamicInstructions });
+      }
+      return new SystemMessage({ content } as BaseMessageFields);
+    }
+
+    return new SystemMessage(
+      [stableInstructions, dynamicInstructions]
+        .filter((part) => part !== '')
+        .join('\n\n')
+    );
+  }
+
   /**
    * Reset context for a new run
    */

package/src/agents/__tests__/AgentContext.anthropic.live.test.ts

@@ -0,0 +1,116 @@
+// src/agents/__tests__/AgentContext.anthropic.live.test.ts
+/**
+ * Live Anthropic prompt-cache verification.
+ *
+ * Run with:
+ * RUN_ANTHROPIC_PROMPT_CACHE_LIVE_TESTS=1 ANTHROPIC_API_KEY=... npm test -- AgentContext.anthropic.live.test.ts --runInBand
+ */
+import { config as dotenvConfig } from 'dotenv';
+dotenvConfig();
+
+import { describe, expect, it } from '@jest/globals';
+import type * as t from '@/types';
+import {
+  runLiveTurn,
+  assertSystemPayloadShape,
+  buildDynamicInstructions,
+  buildStableInstructions,
+  waitForCachePropagation,
+} from './promptCacheLiveHelpers';
+import { Providers } from '@/common';
+
+const shouldRunLive =
+  process.env.RUN_ANTHROPIC_PROMPT_CACHE_LIVE_TESTS === '1' &&
+  process.env.ANTHROPIC_API_KEY != null &&
+  process.env.ANTHROPIC_API_KEY !== '';
+
+const describeIfLive = shouldRunLive ? describe : describe.skip;
+
+const modelName =
+  process.env.ANTHROPIC_PROMPT_CACHE_MODEL ?? 'claude-sonnet-4-5';
+const providerLabel = 'Anthropic';
+
+function createClientOptions(): t.AnthropicClientOptions {
+  return {
+    modelName,
+    temperature: 0,
+    maxTokens: 8,
+    streaming: true,
+    streamUsage: true,
+    promptCache: true,
+    clientOptions: {
+      defaultHeaders: {
+        'anthropic-beta': 'prompt-caching-2024-07-31',
+      },
+    },
+  };
+}
+
+describeIfLive('AgentContext Anthropic prompt cache live API', () => {
+  it('caches only the stable system prefix while dynamic tail changes', async () => {
+    const nonce = `agent-cache-live-${Date.now()}`;
+    const clientOptions = createClientOptions();
+    const stableInstructions = buildStableInstructions({
+      nonce,
+      providerLabel,
+    });
+    const firstDynamicInstructions = buildDynamicInstructions({
+      marker: 'alpha',
+      tailDescription:
+        'The Dynamic Marker line is runtime context and must remain outside the cached prefix.',
+    });
+    const secondDynamicInstructions = buildDynamicInstructions({
+      marker: 'bravo',
+      tailDescription:
+        'The Dynamic Marker line is runtime context and must remain outside the cached prefix.',
+    });
+
+    await assertSystemPayloadShape({
+      agentId: 'live-cache-shape-check',
+      provider: Providers.ANTHROPIC,
+      clientOptions,
+      stableInstructions,
+      dynamicInstructions: firstDynamicInstructions,
+      expectedContent: [
+        {
+          type: 'text',
+          text: stableInstructions,
+          cache_control: { type: 'ephemeral' },
+        },
+        {
+          type: 'text',
+          text: firstDynamicInstructions,
+        },
+      ],
+    });
+
+    const first = await runLiveTurn({
+      provider: Providers.ANTHROPIC,
+      providerLabel,
+      clientOptions,
+      runId: `${nonce}-first`,
+      threadId: `${nonce}-thread`,
+      stableInstructions,
+      dynamicInstructions: firstDynamicInstructions,
+    });
+
+    expect(first.text.toLowerCase()).toContain('alpha');
+    expect(first.usage.input_token_details?.cache_creation).toBeGreaterThan(0);
+    expect(first.usage.input_token_details?.cache_read ?? 0).toBe(0);
+
+    await waitForCachePropagation();
+
+    const second = await runLiveTurn({
+      provider: Providers.ANTHROPIC,
+      providerLabel,
+      clientOptions,
+      runId: `${nonce}-second`,
+      threadId: `${nonce}-thread`,
+      stableInstructions,
+      dynamicInstructions: secondDynamicInstructions,
+    });
+
+    expect(second.text.toLowerCase()).toContain('bravo');
+    expect(second.usage.input_token_details?.cache_read).toBeGreaterThan(0);
+  }, 120_000);
+});