@librechat/agents 3.3.3 → 3.3.5

package/src/messages/alternation.test.ts

@@ -0,0 +1,212 @@
+import { AIMessage, HumanMessage } from '@langchain/core/messages';
+import { Providers } from '@/common';
+import {
+  coalesceAdjacentUserTurns,
+  strictAlternationProviders,
+} from './alternation';
+
+describe('strictAlternationProviders', () => {
+  it('covers the providers that reject consecutive user turns', () => {
+    expect(strictAlternationProviders.has(Providers.BEDROCK)).toBe(true);
+    expect(strictAlternationProviders.has(Providers.MISTRAL)).toBe(true);
+    expect(strictAlternationProviders.has(Providers.MISTRALAI)).toBe(true);
+  });
+
+  it('leaves providers that accept them alone', () => {
+    expect(strictAlternationProviders.has(Providers.ANTHROPIC)).toBe(false);
+    expect(strictAlternationProviders.has(Providers.OPENAI)).toBe(false);
+    expect(strictAlternationProviders.has(Providers.GOOGLE)).toBe(false);
+  });
+});
+
+describe('coalesceAdjacentUserTurns', () => {
+  it('leaves an already-alternating run untouched, returning the SAME array', () => {
+    const messages = [
+      new HumanMessage({ content: 'question' }),
+      new AIMessage({ content: 'answer' }),
+      new HumanMessage({ content: 'follow-up' }),
+    ];
+    const result = coalesceAdjacentUserTurns(messages);
+    /**
+     * Identity, not just equality: the pass runs twice for a primary
+     * Bedrock/Mistral call (createCallModel, then the attemptInvoke funnel),
+     * so the normalized second pass must not reallocate a context-sized
+     * array — and origin tracking early-exits on `before === after`.
+     */
+    expect(result).toBe(messages);
+  });
+
+  it('is idempotent by identity: re-coalescing merged output is a no-op', () => {
+    const once = coalesceAdjacentUserTurns([
+      new HumanMessage({ content: 'steer 1' }),
+      new HumanMessage({ content: 'steer 2' }),
+    ]);
+    expect(once).toHaveLength(1);
+    expect(coalesceAdjacentUserTurns(once)).toBe(once);
+  });
+
+  /** A boundary that drains two steers, which is the ordinary queue case. */
+  it('merges a run of consecutive human turns', () => {
+    const result = coalesceAdjacentUserTurns([
+      new HumanMessage({ content: 'question' }),
+      new AIMessage({ content: 'partial' }),
+      new HumanMessage({ content: 'steer 1' }),
+      new HumanMessage({ content: 'steer 2' }),
+    ]);
+    expect(result.map((m) => m.getType())).toEqual(['human', 'ai', 'human']);
+    expect(result[2].content).toBe('steer 1\n\nsteer 2');
+  });
+
+  it('merges context plus injected messages into one turn', () => {
+    const result = coalesceAdjacentUserTurns([
+      new AIMessage({ content: 'partial' }),
+      new HumanMessage({
+        content: 'hook context',
+        additional_kwargs: { role: 'system', source: 'hook' },
+      }),
+      new HumanMessage({
+        content: 'steer',
+        additional_kwargs: { role: 'user', source: 'steer' },
+      }),
+    ]);
+    expect(result).toHaveLength(2);
+    expect(result[1].content).toBe('hook context\n\nsteer');
+  });
+
+  it('concatenates block content rather than stringifying it', () => {
+    const result = coalesceAdjacentUserTurns([
+      new HumanMessage({ content: [{ type: 'text', text: 'look' }] }),
+      new HumanMessage({
+        content: [{ type: 'image_url', image_url: { url: 'data:,' } }],
+      }),
+    ]);
+    expect(result).toHaveLength(1);
+    expect(result[0].content).toEqual([
+      { type: 'text', text: 'look' },
+      { type: 'image_url', image_url: { url: 'data:,' } },
+    ]);
+  });
+
+  it('normalizes a mixed string and block pair', () => {
+    const result = coalesceAdjacentUserTurns([
+      new HumanMessage({ content: 'plain' }),
+      new HumanMessage({ content: [{ type: 'text', text: 'blocks' }] }),
+    ]);
+    expect(result).toHaveLength(1);
+    expect(result[0].content).toEqual([
+      { type: 'text', text: 'plain' },
+      { type: 'text', text: 'blocks' },
+    ]);
+  });
+
+  /**
+   * Both vendored converters merge adjacent tool-result runs themselves, and
+   * folding one into a text turn would orphan the pairing.
+   */
+  it('never merges tool-result turns', () => {
+    const result = coalesceAdjacentUserTurns([
+      new HumanMessage({
+        content: [{ type: 'tool_result', tool_use_id: 't1', content: 'ok' }],
+      }),
+      new HumanMessage({
+        content: [{ type: 'tool_result', tool_use_id: 't2', content: 'ok' }],
+      }),
+    ]);
+    expect(result).toHaveLength(2);
+  });
+
+  it('never merges a tool-result turn into a text turn', () => {
+    const result = coalesceAdjacentUserTurns([
+      new HumanMessage({
+        content: [{ type: 'tool_result', tool_use_id: 't1', content: 'ok' }],
+      }),
+      new HumanMessage({ content: 'steer' }),
+    ]);
+    expect(result).toHaveLength(2);
+  });
+
+  /**
+   * The prompt-cache tail anchor reasons positionally — it inserts the
+   * breakpoint after the merged message's LAST text block — so the last
+   * part's provenance flags must survive the merge. A skill body absorbed
+   * into a real user turn stays anchorable; a real turn absorbed into a
+   * trailing skill body must not let the anchor pin the volatile body.
+   */
+  it('keeps the last turn\'s additional_kwargs and the first turn\'s id', () => {
+    const result = coalesceAdjacentUserTurns([
+      new HumanMessage({
+        content: 'skill body',
+        id: 'first-id',
+        additional_kwargs: { isMeta: true, source: 'skill' },
+      }),
+      new HumanMessage({
+        content: 'real user turn',
+        id: 'second-id',
+        additional_kwargs: { role: 'user' },
+      }),
+    ]);
+    expect(result).toHaveLength(1);
+    expect(result[0].additional_kwargs).toEqual({ role: 'user' });
+    expect(result[0].id).toBe('first-id');
+  });
+
+  it('marks the merge meta when the trailing part is the volatile one', () => {
+    const result = coalesceAdjacentUserTurns([
+      new HumanMessage({
+        content: 'real steer',
+        additional_kwargs: { source: 'steer' },
+      }),
+      new HumanMessage({
+        content: 'skill body',
+        additional_kwargs: { isMeta: true, source: 'skill', skillName: 'x' },
+      }),
+    ]);
+    expect(result).toHaveLength(1);
+    expect(result[0].additional_kwargs.source).toBe('skill');
+    expect(result[0].additional_kwargs.isMeta).toBe(true);
+  });
+
+  /**
+   * Only ALL-tool-result turns are excluded. A mixed turn is an ordinary
+   * user turn that happens to carry a result block — merging preserves block
+   * order, so the pairing survives, and excluding it would leave adjacent
+   * user turns on the wire for exactly the shape Bedrock rejects.
+   */
+  it('merges a mixed text plus tool-result turn', () => {
+    const result = coalesceAdjacentUserTurns([
+      new HumanMessage({
+        content: [
+          { type: 'tool_result', tool_use_id: 't1', content: 'ok' },
+          { type: 'text', text: 'and my comment' },
+        ],
+      }),
+      new HumanMessage({ content: 'next turn' }),
+    ]);
+    expect(result).toHaveLength(1);
+    expect(result[0].content).toEqual([
+      { type: 'tool_result', tool_use_id: 't1', content: 'ok' },
+      { type: 'text', text: 'and my comment' },
+      { type: 'text', text: 'next turn' },
+    ]);
+  });
+
+  it('excludes the camelCase toolResult variant too', () => {
+    const result = coalesceAdjacentUserTurns([
+      new HumanMessage({
+        content: [{ type: 'toolResult', toolResult: { content: 'ok' } }],
+      }),
+      new HumanMessage({ content: 'steer' }),
+    ]);
+    expect(result).toHaveLength(2);
+  });
+
+  it('does not mutate the input array or its messages', () => {
+    const first = new HumanMessage({ content: 'a' });
+    const second = new HumanMessage({ content: 'b' });
+    const messages = [first, second];
+    coalesceAdjacentUserTurns(messages);
+    expect(messages).toHaveLength(2);
+    expect(first.content).toBe('a');
+    expect(second.content).toBe('b');
+  });
+});

package/src/messages/alternation.ts

@@ -0,0 +1,112 @@
+// src/messages/alternation.ts
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage, MessageContent } from '@langchain/core/messages';
+import { Providers } from '@/common';
+
+/**
+ * Providers whose APIs specify strict user/assistant alternation. Mistral
+ * rejects consecutive user turns outright. Bedrock's Converse API documents
+ * the alternation requirement across many model families; enforcement varies
+ * by family — Claude on Converse currently tolerates adjacent user turns
+ * (verified live, 2026-07-28) — so the payload is normalized for all of them
+ * rather than betting on per-family leniency. Anthropic's own Messages API,
+ * OpenAI and Gemini all accept consecutive user turns, so they are
+ * deliberately absent.
+ */
+export const strictAlternationProviders: ReadonlySet<Providers> = new Set([
+  Providers.BEDROCK,
+  Providers.MISTRAL,
+  Providers.MISTRALAI,
+]);
+
+const TOOL_RESULT_TYPES = new Set(['tool_result', 'toolResult']);
+
+/**
+ * True when every block is a tool result. Both vendored converters already
+ * merge adjacent runs of these, and folding one into a text turn would break
+ * the tool pairing they depend on — so they are left alone here.
+ */
+function isToolResultMessage(message: BaseMessage): boolean {
+  const { content } = message;
+  if (typeof content === 'string' || content.length === 0) {
+    return false;
+  }
+  return content.every(
+    (block) =>
+      typeof block.type === 'string' && TOOL_RESULT_TYPES.has(block.type)
+  );
+}
+
+function toBlocks(content: MessageContent): Exclude<MessageContent, string> {
+  if (typeof content === 'string') {
+    return content === '' ? [] : [{ type: 'text', text: content }];
+  }
+  return content;
+}
+
+function joinContent(
+  left: MessageContent,
+  right: MessageContent
+): MessageContent {
+  if (typeof left === 'string' && typeof right === 'string') {
+    return left === '' ? right : `${left}\n\n${right}`;
+  }
+  return [...toBlocks(left), ...toBlocks(right)];
+}
+
+/**
+ * Merges runs of consecutive human turns into one, for providers that reject
+ * them. Purely a wire-shaping pass: it returns a new array of new messages,
+ * so graph state and the host's persisted messages keep the per-message
+ * identity that steer rendering and the trailing-steer anchor rely on.
+ *
+ * Tool-result turns are excluded — the converters merge those themselves, and
+ * combining one with a text turn would orphan the pairing.
+ */
+export function coalesceAdjacentUserTurns(
+  messages: BaseMessage[]
+): BaseMessage[] {
+  const result: BaseMessage[] = [];
+  let mergedAny = false;
+  for (const message of messages) {
+    const previous = result[result.length - 1];
+    const mergeable =
+      result.length > 0 &&
+      previous.getType() === 'human' &&
+      message.getType() === 'human' &&
+      !isToolResultMessage(previous) &&
+      !isToolResultMessage(message);
+
+    if (!mergeable) {
+      result.push(message);
+      continue;
+    }
+    mergedAny = true;
+
+    result[result.length - 1] = new HumanMessage({
+      content: joinContent(previous.content, message.content),
+      /**
+       * The LATER turn's kwargs, deliberately. The one provider-path consumer
+       * of these flags is the prompt-cache tail anchor, and it reasons
+       * positionally: `isSyntheticMetaMessage` decides whether a breakpoint
+       * may be inserted after the message's LAST text block. Merging keeps
+       * the last block's provenance only if the last part's kwargs survive —
+       * a skill body absorbed into a real user turn must stay anchorable
+       * (the real turn ends it), while a real steer absorbed into a trailing
+       * skill body must not pin the cache to the volatile body. The first
+       * turn's id is kept so origin tracking can re-attach by key.
+       */
+      additional_kwargs: message.additional_kwargs,
+      ...(previous.id != null && { id: previous.id }),
+    });
+  }
+  /**
+   * Identity on the no-merge path. The pass runs twice for a primary
+   * Bedrock/Mistral call — once in `createCallModel` (must precede the cache
+   * breakpoint) and once in the `attemptInvoke` funnel (must cover fallback
+   * and summarization sends) — so the already-normalized second pass returns
+   * the SAME array rather than reallocating a context-sized copy, and
+   * callers can cheaply detect "nothing changed" by identity.
+   */
+  return mergedAny ? result : messages;
+}

package/src/messages/cache.tail.test.ts

@@ -1,3 +1,4 @@
+import { convertMessagesToCompletionsMessageParams } from '@langchain/openai';
 import {
   AIMessage,
   HumanMessage,
@@ -10,7 +11,15 @@ import type {
 } from '@langchain/core/messages';
 import type Anthropic from '@anthropic-ai/sdk';
 import type { AnthropicMessages } from '@/types/messages';
+import {
+  projectOpenAIChatToolMessageContent,
+  projectOpenAIToolMessageContent,
+  projectOpenAIResponsesToolMessageContent,
+  projectOpenRouterToolMessageContent,
+  projectComputerCallOutputsToText,
+} from './core';
 import { addTailCacheControl, addBedrockTailCacheControl } from './cache';
+import { convertToConverseMessages } from '@/llm/bedrock/utils';
 import { toLangChainContent } from './langchain';
 
 type CacheControlBlock = MessageContentComplex & {
@@ -86,6 +95,154 @@ describe('addTailCacheControl (single tail breakpoint)', () => {
     expect(blocksOf(result[2])[0].cache_control).toEqual({ type: 'ephemeral' });
   });
 
+  test('skips native computer outputs and removes stale screenshot markers', () => {
+    const computerCall = new AIMessage({
+      content: '',
+      response_metadata: {
+        output: [
+          {
+            type: 'computer_call',
+            call_id: 'call_computer_cache',
+            action: { type: 'screenshot' },
+          },
+        ],
+      },
+    });
+    const computerOutput = new ToolMessage({
+      content: 'data:image/png;base64,AA==',
+      tool_call_id: 'call_computer_cache',
+      additional_kwargs: { type: 'computer_call_output' },
+    });
+    const canonical = projectOpenAIToolMessageContent([
+      new HumanMessage('Take a screenshot'),
+      computerCall,
+      computerOutput,
+    ]);
+
+    const cached = addTailCacheControl(canonical);
+
+    expect(countCacheMarkers(cached)).toBe(1);
+    expect(blocksOf(cached[0])[0].cache_control).toEqual({
+      type: 'ephemeral',
+    });
+    expect(blocksOf(cached[2])[0]).not.toHaveProperty('cache_control');
+    expect(() =>
+      projectOpenAIResponsesToolMessageContent(cached)
+    ).not.toThrow();
+
+    const canonicalOutput = canonical[2] as ToolMessage;
+    const staleOutput = new ToolMessage({
+      content: toLangChainContent([
+        {
+          ...(canonicalOutput.content[0] as MessageContentComplex),
+          cache_control: { type: 'ephemeral' },
+        },
+      ]),
+      tool_call_id: canonicalOutput.tool_call_id,
+      additional_kwargs: canonicalOutput.additional_kwargs,
+    });
+    const cleaned = addTailCacheControl([
+      canonical[0],
+      canonical[1],
+      staleOutput,
+    ]);
+
+    expect(countCacheMarkers(cleaned)).toBe(1);
+    expect(blocksOf(cleaned[2])[0]).not.toHaveProperty('cache_control');
+    expect(blocksOf(staleOutput)[0]).toHaveProperty('cache_control');
+    expect(() =>
+      projectOpenAIResponsesToolMessageContent(cleaned)
+    ).not.toThrow();
+  });
+
+  test('keeps a cached tool result structured through Chat projection', () => {
+    const toolCall = new AIMessage({
+      content: '',
+      tool_calls: [{ id: 'call_cached_tool', name: 'search', args: {} }],
+    });
+    const toolOutput = new ToolMessage({
+      content: 'result body',
+      tool_call_id: 'call_cached_tool',
+    });
+    const graphProjected = projectOpenAIToolMessageContent([
+      new HumanMessage('Search'),
+      toolCall,
+      toolOutput,
+    ]);
+    const cached = addTailCacheControl(graphProjected);
+    const attemptProjected = projectOpenRouterToolMessageContent(cached);
+    const payload = convertMessagesToCompletionsMessageParams({
+      messages: attemptProjected,
+      model: 'gpt-4o',
+    });
+
+    expect(blocksOf(cached[2])[0]).toMatchObject({
+      type: 'text',
+      text: 'result body',
+      cache_control: { type: 'ephemeral' },
+    });
+    expect((attemptProjected[2] as ToolMessage).content).toEqual(
+      (cached[2] as ToolMessage).content
+    );
+    expect(payload[2]).toMatchObject({
+      role: 'tool',
+      tool_call_id: 'call_cached_tool',
+      content: [
+        {
+          type: 'text',
+          text: 'result body',
+          cache_control: { type: 'ephemeral' },
+        },
+      ],
+    });
+
+    const fallbackProjected = projectOpenAIChatToolMessageContent(cached);
+    const fallbackPayload = convertMessagesToCompletionsMessageParams({
+      messages: fallbackProjected,
+      model: 'gpt-4o',
+    });
+
+    expect((fallbackProjected[2] as ToolMessage).content).toBe('result body');
+    expect(fallbackPayload[2]).toMatchObject({
+      role: 'tool',
+      tool_call_id: 'call_cached_tool',
+      content: 'result body',
+    });
+    expect(JSON.stringify(fallbackPayload[2])).not.toContain('cache_control');
+
+    expect(
+      typeof (projectOpenAIToolMessageContent(cached)[2] as ToolMessage).content
+    ).toBe('string');
+  });
+
+  test('does not stringify noncanonical cache metadata into tool output', () => {
+    const messages = addTailCacheControl<BaseMessage>([
+      new HumanMessage('Search'),
+      new AIMessage({
+        content: '',
+        tool_calls: [{ id: 'call_nested_cache', name: 'search', args: {} }],
+      }),
+      new ToolMessage({
+        content: toLangChainContent([
+          {
+            type: 'tool_result',
+            tool_use_id: 'call_nested_cache',
+            content: 'result body',
+          },
+        ] as MessageContentComplex[]),
+        tool_call_id: 'call_nested_cache',
+      }),
+    ]);
+
+    const projected = projectOpenRouterToolMessageContent(messages);
+    const content = (projected[2] as ToolMessage).content;
+
+    expect(typeof content).toBe('string');
+    expect(content).toContain('result body');
+    expect(content).not.toContain('cache_control');
+    expect(JSON.stringify(messages[2].content)).toContain('cache_control');
+  });
+
   test('strips ALL stale markers and re-anchors a single one at the tail', () => {
     const messages: BaseMessage[] = [
       new HumanMessage({
@@ -337,4 +494,40 @@ describe('addBedrockTailCacheControl (single tail cachePoint)', () => {
       { cachePoint: { type: 'default' } },
     ]);
   });
+
+  test('keeps the cachePoint before an omitted computer screenshot', () => {
+    const computerOutput = new ToolMessage({
+      content: 'data:image/png;base64,AA==',
+      tool_call_id: 'call_bedrock_computer',
+      additional_kwargs: { type: 'computer_call_output' },
+    });
+    const cached = addBedrockTailCacheControl([
+      new HumanMessage('Take a screenshot'),
+      new AIMessage({
+        content: '',
+        tool_calls: [
+          {
+            id: 'call_bedrock_computer',
+            name: 'computer',
+            args: { action: 'screenshot' },
+          },
+        ],
+      }),
+      computerOutput,
+    ]);
+
+    expect(countCachePoints(cached)).toBe(1);
+    expect(blocksOf(cached[0])[1]).toEqual({
+      cachePoint: { type: 'default' },
+    });
+    expect(cached[2].content).toBe(computerOutput.content);
+
+    const projected = projectComputerCallOutputsToText(cached);
+    const converse = convertToConverseMessages(projected);
+    expect((projected[2] as ToolMessage).content).toBe(
+      '[Computer screenshot omitted for this provider]'
+    );
+    expect(JSON.stringify(converse).match(/"cachePoint"/g)).toHaveLength(1);
+    expect(computerOutput.content).toBe('data:image/png;base64,AA==');
+  });
 });

package/src/messages/cache.test.ts

@@ -1029,6 +1029,87 @@ describe('stripAnthropicCacheControl', () => {
     expect(result[0].content).toBe('Hello');
   });
 
+  it('ignores primitive and proxy blocks without invoking proxy traps', () => {
+    const unsafe = new Proxy(
+      {},
+      {
+        ownKeys() {
+          throw new Error('proxy keys must not be inspected');
+        },
+      }
+    );
+    const content = [
+      'primitive',
+      unsafe,
+      {
+        type: ContentTypes.TEXT,
+        text: 'cached',
+        cache_control: { type: 'ephemeral' },
+      },
+    ] as unknown as MessageContentComplex[];
+
+    const result = stripAnthropicCacheControl([{ role: 'user', content }]);
+    const stripped = result[0].content as unknown[];
+
+    expect(stripped[0]).toBe('primitive');
+    expect(stripped[1]).toBe(unsafe);
+    expect(stripped[2]).toEqual({
+      type: ContentTypes.TEXT,
+      text: 'cached',
+    });
+  });
+
+  it('removes a non-configurable cache_control from the clone only', () => {
+    const block = { type: ContentTypes.TEXT, text: 'cached' };
+    Object.defineProperty(block, 'cache_control', {
+      configurable: false,
+      enumerable: true,
+      value: { type: 'ephemeral' },
+      writable: false,
+    });
+    const messages = [
+      {
+        role: 'user',
+        content: [block as MessageContentComplex],
+      },
+    ];
+
+    const result = stripAnthropicCacheControl(messages);
+    const stripped = (result[0].content as MessageContentComplex[])[0];
+
+    expect('cache_control' in stripped).toBe(false);
+    expect(
+      (block as typeof block & { cache_control: unknown }).cache_control
+    ).toEqual({ type: 'ephemeral' });
+  });
+
+  it('removes an accessor cache_control without invoking it', () => {
+    let getterCalls = 0;
+    const block = { type: ContentTypes.TEXT, text: 'cached' };
+    Object.defineProperty(block, 'cache_control', {
+      configurable: true,
+      enumerable: true,
+      get() {
+        getterCalls++;
+        throw new Error('cache getter must not run');
+      },
+    });
+
+    const result = stripAnthropicCacheControl([
+      {
+        role: 'user',
+        content: [block as MessageContentComplex],
+      },
+    ]);
+    const stripped = (result[0].content as MessageContentComplex[])[0];
+
+    expect(getterCalls).toBe(0);
+    expect('cache_control' in stripped).toBe(false);
+    expect(
+      Object.getOwnPropertyDescriptor(block, 'cache_control')
+    ).toBeDefined();
+  });
+
   it('returns non-array input unchanged', () => {
     const notArray = 'not an array';
     /** @ts-expect-error - Testing invalid input */
@@ -1074,6 +1155,38 @@ describe('stripBedrockCacheControl', () => {
     });
   });
 
+  it('ignores primitive and proxy blocks while removing cache points', () => {
+    let getterCalls = 0;
+    const unsafe = new Proxy(
+      {},
+      {
+        getOwnPropertyDescriptor() {
+          throw new Error('proxy descriptors must not be inspected');
+        },
+      }
+    );
+    const accessorCachePoint = {};
+    Object.defineProperty(accessorCachePoint, 'cachePoint', {
+      configurable: true,
+      enumerable: true,
+      get() {
+        getterCalls++;
+        throw new Error('cache point getter must not run');
+      },
+    });
+    const content = [
+      42,
+      unsafe,
+      accessorCachePoint,
+      { cachePoint: { type: 'default' } },
+    ] as unknown as MessageContentComplex[];
+
+    const result = stripBedrockCacheControl([{ role: 'user', content }]);
+
+    expect(result[0].content).toEqual([42, unsafe]);
+    expect(getterCalls).toBe(0);
+  });
+
   it('handles messages without cachePoint blocks gracefully', () => {
     const messages: TestMsg[] = [
       {