@librechat/agents 3.3.4 → 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/format.ts

@@ -475,6 +475,25 @@ function formatToolCallOutput(
   return compactToolContent(output, HARD_MAX_TOOL_RESULT_CHARS).content;
 }
 
+/**
+ * Content for the synthetic assistant turn that separates a trailing steer
+ * from the next user turn. Non-empty by necessity — see the push site.
+ */
+const STEER_ANCHOR_PLACEHOLDER = '_';
+
+/**
+ * True when an assistant message replayed as a steer and nothing followed it,
+ * so the emitted run ends on the steer's `HumanMessage`.
+ */
+function endsWithSteerMessage(
+  formatted: Array<RoleBearingMessage<BaseMessage>>
+): boolean {
+  if (formatted.length === 0) {
+    return false;
+  }
+  return formatted[formatted.length - 1].additional_kwargs.source === 'steer';
+}
+
 /**
  * Helper function to format an assistant message
  * @param message The message to format
@@ -1336,6 +1355,36 @@ export const formatAgentMessages = (
     | RoleBearingMessage<SystemMessage>
     | RoleBearingMessage<ToolMessage>
   > = [];
+  /**
+   * A steer ended the previous payload entry, so the next message emitted —
+   * whichever entry finally produces one — must be separated from it by an
+   * assistant turn. Held rather than emitted so an entry that produces
+   * nothing cannot leave the anchor stranded as the final turn.
+   */
+  let pendingSteerAnchor = false;
+  /**
+   * Emits the deferred anchor ahead of `next` — the message about to be
+   * pushed. When that message is itself an assistant turn, it already IS the
+   * separation the anchor exists to synthesize, so the intent is simply
+   * discharged: emitting the placeholder anyway would put two assistant turns
+   * back to back, which strict-alternation providers can reject and nothing downstream
+   * repairs (`coalesceAdjacentUserTurns` merges user turns only).
+   */
+  const flushSteerAnchor = (next: { role?: LangChainMessageRole }): void => {
+    if (!pendingSteerAnchor) {
+      return;
+    }
+    pendingSteerAnchor = false;
+    if (next.role === 'assistant') {
+      return;
+    }
+    messages.push(
+      withMessageRole(
+        new AIMessage({ content: STEER_ANCHOR_PLACEHOLDER }),
+        'assistant'
+      )
+    );
+  };
   // If indexTokenCountMap is provided, create a new map to track the updated indices
   const updatedIndexTokenCountMap: Record<number, number> = {};
   let boundaryTokenAdjustment:
@@ -1397,6 +1446,7 @@ export const formatAgentMessages = (
       if (sourceMessageId != null && sourceMessageId !== '') {
         formattedMessage.id = sourceMessageId;
       }
+      flushSteerAnchor(formattedMessage);
       messages.push(formattedMessage);
 
       // Update the index mapping for this message
@@ -1580,7 +1630,48 @@ export const formatAgentMessages = (
         formattedMessage.id = sourceMessageId;
       }
     }
+    /**
+     * A steer that ends an assistant message leaves the replay on a
+     * `HumanMessage`. The next payload message is itself a user turn, so the
+     * sequence would reach the provider as two adjacent user turns — rejected
+     * by strict-alternation providers. Anchor it with a placeholder assistant
+     * turn.
+     *
+     * The placeholder must be NON-EMPTY. A string-content assistant message
+     * with no tool calls passes through `_convertMessagesToAnthropicPayload`
+     * verbatim — the empty-text repair there only covers array content and
+     * tool-call turns — so an empty anchor would reach Anthropic as
+     * `{role: 'assistant', content: ''}` and trade one invalid sequence for
+     * another. Same single-underscore convention the Anthropic converter
+     * already uses when it has to synthesize a non-empty block.
+     *
+     * Deferred rather than decided by lookahead. `i < payload.length - 1` only
+     * proves a later ENTRY exists, not that it EMITS: entries with empty
+     * content, and entries dropped by `applySummaryBoundary`, are skipped
+     * silently. A trailing steer followed only by those would get the anchor
+     * as the FINAL turn — an assistant prefill with no request after it, which
+     * the model may simply never answer. So the intent is recorded and flushed
+     * only when a message actually follows.
+     *
+     * Pushed AFTER the id stamping above, deliberately. `messagesStateReducer`
+     * treats a repeated id as replace-in-place, so an anchor carrying the
+     * shared `sourceMessageId` would overwrite the steer it exists to protect.
+     * Left unstamped, it reaches the reducer with a null id and is assigned a
+     * fresh one. `endsWithSteerMessage` reads only `additional_kwargs.source`,
+     * so the deferral cannot change which messages get anchored.
+     */
+    /**
+     * Guarded on emission: an assistant entry whose blocks all filtered away
+     * emits nothing, and flushing for it would strand the anchor as the final
+     * turn — the pending flag stays set for whichever entry emits next.
+     */
+    if (formattedMessages.length > 0) {
+      flushSteerAnchor(formattedMessages[0]);
+    }
     messages.push(...formattedMessages);
+    if (endsWithSteerMessage(formattedMessages)) {
+      pendingSteerAnchor = true;
+    }
 
     // Capture index range BEFORE skill body injection so injected
     // HumanMessages are excluded from the assistant's token distribution.