@librechat/agents 3.3.4 → 3.3.6

package/src/messages/formatAgentMessages.steer.test.ts

@@ -1,5 +1,6 @@
 import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
 import type { TPayload } from '@/types';
+import { _convertMessagesToAnthropicPayload } from '@/llm/anthropic/utils/message_inputs';
 import { ContentTypes, Constants, Providers } from '@/common';
 import { formatAgentMessages } from './format';
 
@@ -324,3 +325,269 @@ describe('formatAgentMessages steer replay', () => {
     ]);
   });
 });
+
+describe('formatAgentMessages trailing-steer anchor', () => {
+  const steerPart = (text: string): Record<string, unknown> =>
+    ({
+      type: ContentTypes.STEER,
+      [ContentTypes.STEER]: text,
+    }) as unknown as Record<string, unknown>;
+
+  /**
+   * A steer that ends an assistant message leaves the replay on a
+   * HumanMessage. Followed by the next turn's user message, that reaches the
+   * provider as two adjacent user turns — a hard error on Bedrock and
+   * Mistral. Reachable today through abort, not only through preemption.
+   */
+  it('anchors a trailing steer when another turn follows', () => {
+    const payload: TPayload = [
+      { role: 'user', content: 'Original request' },
+      {
+        role: 'assistant',
+        content: [
+          { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Working on it.' },
+          steerPart('Actually, stop and do the other thing.'),
+        ],
+      },
+      { role: 'user', content: 'Next turn' },
+    ];
+
+    const { messages } = formatAgentMessages(payload);
+
+    const steerIndex = messages.findIndex(
+      (message) =>
+        message instanceof HumanMessage &&
+        message.additional_kwargs.source === 'steer'
+    );
+    expect(steerIndex).toBeGreaterThan(0);
+
+    const anchor = messages[steerIndex + 1];
+    expect(anchor).toBeInstanceOf(AIMessage);
+    expect(anchor.content).not.toBe('');
+
+    const following = messages[steerIndex + 2];
+    expect(following).toBeInstanceOf(HumanMessage);
+    expect(following.content).toEqual([{ type: 'text', text: 'Next turn' }]);
+  });
+
+  /**
+   * `messagesStateReducer` treats a repeated id as replace-in-place, so an
+   * anchor stamped with the shared `sourceMessageId` would overwrite the very
+   * steer it exists to protect. It must reach the reducer unstamped.
+   */
+  it('does not stamp the anchor with the shared source message id', () => {
+    const payload: TPayload = [
+      { role: 'user', content: 'Original request' },
+      {
+        messageId: 'assistant_1',
+        role: 'assistant',
+        content: [
+          { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Partial answer.' },
+          steerPart('Change of plan.'),
+        ],
+      } as unknown as TPayload[number],
+      { role: 'user', content: 'Next turn' },
+    ];
+
+    const { messages } = formatAgentMessages(payload);
+
+    const steerIndex = messages.findIndex(
+      (message) => message.additional_kwargs.source === 'steer'
+    );
+    expect(steerIndex).toBeGreaterThan(0);
+    expect(messages[steerIndex].id).toBe('assistant_1');
+    expect(messages[steerIndex - 1].id).toBe('assistant_1');
+
+    const anchor = messages[steerIndex + 1];
+    expect(anchor).toBeInstanceOf(AIMessage);
+    expect(anchor.content).not.toBe('');
+    expect(anchor.id).not.toBe('assistant_1');
+  });
+
+  /**
+   * The anchor exists to keep the sequence provider-valid, so the assertion
+   * that matters is what a provider actually receives. An empty-string
+   * assistant turn with no tool calls survives the Anthropic converter
+   * verbatim — the empty-text repair covers only array content and tool-call
+   * turns — so an empty anchor would trade adjacent user turns for an
+   * empty-content 400.
+   */
+  it('survives the Anthropic converter with non-empty assistant content', () => {
+    const payload: TPayload = [
+      { role: 'user', content: 'Original request' },
+      {
+        role: 'assistant',
+        content: [
+          { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Partial answer.' },
+          steerPart('Change of plan.'),
+        ],
+      },
+      { role: 'user', content: 'Next turn' },
+    ];
+
+    const { messages } = formatAgentMessages(payload);
+    const { messages: anthropicMessages } =
+      _convertMessagesToAnthropicPayload(messages);
+
+    for (const message of anthropicMessages) {
+      if (message.role !== 'assistant') {
+        continue;
+      }
+      if (typeof message.content === 'string') {
+        expect(message.content.trim()).not.toBe('');
+        continue;
+      }
+      expect(message.content.length).toBeGreaterThan(0);
+    }
+
+    const roles = anthropicMessages.map((message) => message.role);
+    for (let i = 1; i < roles.length; i++) {
+      expect(roles[i] === 'user' && roles[i - 1] === 'user').toBe(false);
+    }
+  });
+
+  /**
+   * The old lookahead only proved a later ENTRY existed, not that it emitted.
+   * An entry with empty content is skipped silently, so a trailing steer
+   * followed only by such entries would leave the anchor as the final turn —
+   * an assistant prefill with no request after it.
+   */
+  it('omits the anchor when no later payload entry emits a message', () => {
+    const payload: TPayload = [
+      { role: 'user', content: 'Original request' },
+      {
+        role: 'assistant',
+        content: [
+          { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Partial answer.' },
+          steerPart('Change of plan.'),
+        ],
+      },
+      { role: 'user', content: [] } as unknown as TPayload[number],
+    ];
+
+    const { messages } = formatAgentMessages(payload);
+    const last = messages[messages.length - 1];
+    expect(last.additional_kwargs.source).toBe('steer');
+    expect(
+      messages.some(
+        (m) => m instanceof AIMessage && m.content === '_'
+      )
+    ).toBe(false);
+  });
+
+  it('leaves the user turn last when the steer ends the payload', () => {
+    const payload: TPayload = [
+      { role: 'user', content: 'Original request' },
+      {
+        role: 'assistant',
+        content: [
+          { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Working on it.' },
+          steerPart('Actually, stop and do the other thing.'),
+        ],
+      },
+    ];
+
+    const { messages } = formatAgentMessages(payload);
+
+    const last = messages[messages.length - 1];
+    expect(last).toBeInstanceOf(HumanMessage);
+    expect(last.additional_kwargs.source).toBe('steer');
+  });
+
+  it('does not anchor when assistant content follows the steer', () => {
+    const payload: TPayload = [
+      { role: 'user', content: 'Original request' },
+      {
+        role: 'assistant',
+        content: [
+          { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Working on it.' },
+          steerPart('Focus on item two.'),
+          { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Focusing.' },
+        ],
+      },
+      { role: 'user', content: 'Next turn' },
+    ];
+
+    const { messages } = formatAgentMessages(payload);
+
+    const emptyAssistants = messages.filter(
+      (message) => message instanceof AIMessage && message.content === ''
+    );
+    expect(emptyAssistants).toHaveLength(0);
+  });
+
+  /**
+   * A trailing steer followed by another assistant ENTRY needs no anchor —
+   * that entry's own assistant turn IS the separation. Emitting the
+   * placeholder anyway would put two assistant turns back to back, which
+   * strict-alternation providers can reject and nothing downstream merges
+   * (`coalesceAdjacentUserTurns` merges user turns only).
+   */
+  it('suppresses the anchor when the next payload entry is an assistant turn', () => {
+    const payload: TPayload = [
+      { role: 'user', content: 'Original request' },
+      {
+        role: 'assistant',
+        content: [
+          { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Working on it.' },
+          steerPart('Actually, do the other thing.'),
+        ],
+      },
+      {
+        role: 'assistant',
+        content: [
+          { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Doing the other thing.' },
+        ],
+      },
+    ];
+
+    const { messages } = formatAgentMessages(payload);
+
+    expect(messages.map((message) => message.constructor.name)).toEqual([
+      'HumanMessage',
+      'AIMessage',
+      'HumanMessage',
+      'AIMessage',
+    ]);
+    expect(messages[2].additional_kwargs.source).toBe('steer');
+    expect(messages[3].content).toEqual([
+      { type: 'text', text: 'Doing the other thing.' },
+    ]);
+    expect(
+      messages.some(
+        (message) => message instanceof AIMessage && message.content === '_'
+      )
+    ).toBe(false);
+  });
+
+  it('never emits two adjacent user turns around a trailing steer', () => {
+    const payload: TPayload = [
+      { role: 'user', content: 'Original request' },
+      {
+        role: 'assistant',
+        content: [
+          { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Partial answer.' },
+          steerPart('Change of plan.'),
+        ],
+      },
+      { role: 'user', content: 'Next turn' },
+      {
+        role: 'assistant',
+        content: [
+          { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Second answer.' },
+          steerPart('Change again.'),
+        ],
+      },
+      { role: 'user', content: 'Third turn' },
+    ];
+
+    const { messages } = formatAgentMessages(payload);
+
+    for (let i = 1; i < messages.length; i++) {
+      const adjacentHumans =
+        messages[i] instanceof HumanMessage &&
+        messages[i - 1] instanceof HumanMessage;
+      expect(adjacentHumans).toBe(false);
+    }
+  });
+});

package/src/messages/handoffCue.test.ts

@@ -0,0 +1,96 @@
+import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import {
+  appendPredecessorHandoffCue,
+  removePredecessorHandoffCue,
+  PREDECESSOR_HANDOFF_CUE,
+} from './handoffCue';
+
+const runAi = new AIMessage({ content: 'predecessor output', id: 'run-ai-1' });
+const producedIds = new Set(['run-ai-1']);
+const isRunProduced = (message: BaseMessage): boolean =>
+  message.id != null && producedIds.has(message.id);
+
+describe('appendPredecessorHandoffCue', () => {
+  it('appends the cue when the payload ends with a run-produced assistant turn', () => {
+    const payload = [new HumanMessage('ask'), runAi];
+    const result = appendPredecessorHandoffCue(payload, isRunProduced);
+    expect(result).toHaveLength(3);
+    expect(result[2].content).toBe(PREDECESSOR_HANDOFF_CUE);
+    expect(result[2].additional_kwargs).toEqual({
+      role: 'user',
+      isMeta: true,
+      source: 'handoff',
+    });
+    /** Non-mutating: the input array is untouched. */
+    expect(payload).toHaveLength(2);
+  });
+
+  it('matches a transformed clone of the run tail by id', () => {
+    const clone = new AIMessage({ content: 'projected copy', id: 'run-ai-1' });
+    expect(appendPredecessorHandoffCue([clone], isRunProduced)).toHaveLength(2);
+  });
+
+  /**
+   * Host-supplied trailing assistant turns are deliberate prefill (continue
+   * generation flows). The run has not produced them, so provenance never
+   * matches and the cue must stay off.
+   */
+  it('leaves host-history prefill payloads alone', () => {
+    const hostAi = new AIMessage({ content: 'host prefill', id: 'host-ai-9' });
+    expect(appendPredecessorHandoffCue([hostAi], isRunProduced)).toHaveLength(
+      1
+    );
+    expect(appendPredecessorHandoffCue([hostAi], undefined)).toHaveLength(1);
+  });
+
+  it('is off when the payload does not end on an assistant turn', () => {
+    const tool = new ToolMessage({ content: 'r', tool_call_id: 't1' });
+    expect(
+      appendPredecessorHandoffCue([runAi, tool], isRunProduced)
+    ).toHaveLength(2);
+    expect(
+      appendPredecessorHandoffCue([new HumanMessage('hi')], isRunProduced)
+    ).toHaveLength(1);
+    expect(appendPredecessorHandoffCue([], isRunProduced)).toHaveLength(0);
+  });
+
+  it('fails safe when the tail carries no id', () => {
+    const noId = new AIMessage({ content: 'no id' });
+    expect(appendPredecessorHandoffCue([noId], isRunProduced)).toHaveLength(1);
+  });
+});
+
+describe('removePredecessorHandoffCue', () => {
+  const cue = new HumanMessage({
+    content: PREDECESSOR_HANDOFF_CUE,
+    additional_kwargs: { role: 'user', isMeta: true, source: 'handoff' },
+  });
+
+  it('strips a trailing cue and only a trailing cue', () => {
+    const stripped = removePredecessorHandoffCue([runAi, cue]);
+    expect(stripped).toHaveLength(1);
+    expect(stripped[0]).toBe(runAi);
+  });
+
+  it('is identity when no cue trails', () => {
+    const messages = [runAi];
+    expect(removePredecessorHandoffCue(messages)).toBe(messages);
+    const userTail = [runAi, new HumanMessage('real user turn')];
+    expect(removePredecessorHandoffCue(userTail)).toBe(userTail);
+    const empty: BaseMessage[] = [];
+    expect(removePredecessorHandoffCue(empty)).toBe(empty);
+  });
+
+  it('does not strip a user turn that merely repeats the cue text', () => {
+    const impostor = new HumanMessage({ content: PREDECESSOR_HANDOFF_CUE });
+    const messages = [runAi, impostor];
+    expect(removePredecessorHandoffCue(messages)).toBe(messages);
+  });
+
+  it('round-trips with append', () => {
+    const payload = [new HumanMessage('ask'), runAi];
+    const appended = appendPredecessorHandoffCue(payload, isRunProduced);
+    expect(removePredecessorHandoffCue(appended)).toEqual(payload);
+  });
+});

package/src/messages/handoffCue.ts

@@ -0,0 +1,78 @@
+// src/messages/handoffCue.ts
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+
+/**
+ * Bracketed-meta convention, like the handoff path's
+ * `[Processed tool result and transferring to …]` bridge. The wording makes
+ * two things unambiguous to the model: the assistant turn above is FINISHED,
+ * and it belongs to a previous stage — so the successor answers as itself
+ * instead of continuing someone else's sentence.
+ */
+export const PREDECESSOR_HANDOFF_CUE =
+  '[The assistant message above is the completed output of a previous ' +
+  'agent. Respond now according to your own role and instructions.]';
+
+/**
+ * Appends a user-turn handoff cue when a payload ends with an assistant turn
+ * that THIS RUN produced — which only happens when a different agent in a
+ * multi-agent workflow produced it (an agent's own self-loops always re-enter
+ * on a tool result or an injected user turn).
+ *
+ * Why: providers with prefill semantics (Anthropic, Bedrock-Claude) treat a
+ * trailing assistant message as a prefill and CONTINUE it. A bare direct-edge
+ * successor therefore speaks in its predecessor's voice — or, when the
+ * trailing turn reads complete (a preemption steer's short resume, say),
+ * returns empty content (danny-avila/agents#345, reproduced live 3/3).
+ * Handoff edges with instructions and prompt-instruction edges already break
+ * the prefill with a user turn; this closes the same gap for bare edges.
+ *
+ * Fail-safe OFF by provenance: the trailing payload message must be one the
+ * run itself produced (`isRunProduced`, backed by the graph's run-produced id
+ * set — immune to summarization compaction, which rewrites the live array
+ * and stales index-based boundaries). Host-supplied trailing assistant
+ * turns (deliberate prefill flows) never match — the run has not produced
+ * them — so single-agent prefill behavior is untouched. Wire-only: the cue is
+ * appended to the provider projection, never to graph state or host history.
+ */
+export function appendPredecessorHandoffCue(
+  messages: BaseMessage[],
+  isRunProduced: ((message: BaseMessage) => boolean) | undefined
+): BaseMessage[] {
+  const last = messages.at(-1);
+  if (last == null || last.getType() !== 'ai') {
+    return messages;
+  }
+  if (isRunProduced == null || !isRunProduced(last)) {
+    return messages;
+  }
+  return [
+    ...messages,
+    new HumanMessage({
+      content: PREDECESSOR_HANDOFF_CUE,
+      additional_kwargs: { role: 'user', isMeta: true, source: 'handoff' },
+    }),
+  ];
+}
+
+/**
+ * Strips a trailing handoff cue. The counterpart for the serving-provider
+ * funnel: an Anthropic-like PRIMARY bakes the cue into its measured payload,
+ * and a tolerant fallback (OpenAI, Mistral, Bedrock-Nova) re-sending that
+ * payload must not ship the Claude-only synthetic turn. Identity on the
+ * no-op path.
+ */
+export function removePredecessorHandoffCue(
+  messages: BaseMessage[]
+): BaseMessage[] {
+  const last = messages.at(-1);
+  if (
+    last == null ||
+    last.getType() !== 'human' ||
+    last.additional_kwargs.source !== 'handoff' ||
+    last.content !== PREDECESSOR_HANDOFF_CUE
+  ) {
+    return messages;
+  }
+  return messages.slice(0, -1);
+}

package/src/messages/index.ts

@@ -7,6 +7,9 @@ export * from './cache';
 export * from './anthropicToolCache';
 export * from './content';
 export * from './tools';
+export * from './injected';
+export * from './alternation';
+export * from './handoffCue';
 export * from './contextPruning';
 export * from './contextPruningSettings';
 export * from './reducer';

package/src/messages/injected.test.ts

@@ -0,0 +1,90 @@
+import { HumanMessage } from '@langchain/core/messages';
+import type { InjectedMessage } from '@/types/tools';
+import { convertInjectedMessages } from './injected';
+
+describe('convertInjectedMessages', () => {
+  it('returns an empty array for no entries', () => {
+    expect(convertInjectedMessages([])).toEqual([]);
+  });
+
+  it('emits one HumanMessage per entry, in order', () => {
+    const messages: InjectedMessage[] = [
+      { role: 'user', content: 'first' },
+      { role: 'user', content: 'second' },
+    ];
+    const converted = convertInjectedMessages(messages);
+    expect(converted).toHaveLength(2);
+    expect(converted[0]).toBeInstanceOf(HumanMessage);
+    expect(converted[0].content).toBe('first');
+    expect(converted[1].content).toBe('second');
+  });
+
+  /**
+   * Both 'user' and 'system' become `HumanMessage` — Anthropic and Google
+   * reject a non-leading SystemMessage — with the original role preserved for
+   * downstream consumers.
+   */
+  it('converts a system role to a HumanMessage carrying the original role', () => {
+    const [converted] = convertInjectedMessages([
+      { role: 'system', content: 'convention reminder' },
+    ]);
+    expect(converted).toBeInstanceOf(HumanMessage);
+    expect(converted.additional_kwargs.role).toBe('system');
+  });
+
+  it('carries isMeta, source and skillName only when set', () => {
+    const [bare] = convertInjectedMessages([{ role: 'user', content: 'x' }]);
+    expect(bare.additional_kwargs).toEqual({ role: 'user' });
+
+    const [full] = convertInjectedMessages([
+      {
+        role: 'user',
+        content: 'x',
+        isMeta: true,
+        source: 'steer',
+        skillName: 'writing',
+      },
+    ]);
+    expect(full.additional_kwargs).toEqual({
+      role: 'user',
+      isMeta: true,
+      source: 'steer',
+      skillName: 'writing',
+    });
+  });
+
+  it('passes multimodal content through as a content array', () => {
+    const [converted] = convertInjectedMessages([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'look at this' },
+          { type: 'image_url', image_url: { url: 'data:image/png;base64,AA' } },
+        ],
+      },
+    ]);
+    expect(Array.isArray(converted.content)).toBe(true);
+    expect(converted.content).toHaveLength(2);
+  });
+
+  /**
+   * The provider-safety argument for sealing a stream mid-generation rests on
+   * the preempt boundary emitting exactly what the already-shipped tool
+   * boundary emits. Both call this function, so shape parity is structural —
+   * this pins it against a future divergence.
+   */
+  it('produces identical shapes for the same entry across calls', () => {
+    const entry: InjectedMessage = {
+      role: 'user',
+      content: 'Skip phase two.',
+      source: 'steer',
+    };
+    const [atToolBoundary] = convertInjectedMessages([entry]);
+    const [atPreemptBoundary] = convertInjectedMessages([entry]);
+    expect(atPreemptBoundary.content).toEqual(atToolBoundary.content);
+    expect(atPreemptBoundary.additional_kwargs).toEqual(
+      atToolBoundary.additional_kwargs
+    );
+    expect(atPreemptBoundary.getType()).toBe(atToolBoundary.getType());
+  });
+});

package/src/messages/injected.ts

@@ -0,0 +1,74 @@
+// src/messages/injected.ts
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { InjectedMessage } from '@/types/tools';
+import { ContentTypes } from '@/common';
+import { toLangChainContent } from './langchain';
+
+/**
+ * Converts `InjectedMessage` instances to LangChain `HumanMessage` objects.
+ * Both 'user' and 'system' roles become `HumanMessage` to avoid provider
+ * rejections (Anthropic/Google reject non-leading SystemMessages). The
+ * original role is preserved in `additional_kwargs` for downstream consumers.
+ *
+ * Shared by both injection boundaries — `ToolNode`'s tool-batch dispatch and
+ * `StandardGraph`'s preempt-boundary dispatch. Keeping one implementation is
+ * load-bearing rather than tidy: the provider-safety argument for sealing a
+ * stream mid-generation rests on the injected turn having byte-identical
+ * shape to the one the already-shipped tool boundary emits, so the two sites
+ * must not be able to drift.
+ */
+/**
+ * True when an entry carries nothing a provider will accept as a turn.
+ *
+ * The public `InjectedMessage` type admits `content: ''` and `content: []`,
+ * and a host hook is free to return one. Converting it anyway produces a
+ * `HumanMessage` that passes the caller's `length > 0` test, so the graph
+ * resumes and sends a trailing EMPTY user turn — which Anthropic and other
+ * strict providers reject outright, turning a cooperative seal into a failed
+ * run. Permissive providers merely burn a model call.
+ *
+ * Whitespace counts as empty, matching the standard `canSealPreempt` applies
+ * to the assistant side of the same pair. Non-text blocks count as content: a
+ * media-only steer is a real turn and must survive.
+ */
+function isEmptyInjectedContent(content: InjectedMessage['content']): boolean {
+  if (typeof content === 'string') {
+    return content.trim() === '';
+  }
+  if (content.length === 0) {
+    return true;
+  }
+  return content.every((block) => {
+    if (block.type !== ContentTypes.TEXT) {
+      return false;
+    }
+    const text = block[ContentTypes.TEXT];
+    return typeof text !== 'string' || text.trim() === '';
+  });
+}
+
+export function convertInjectedMessages(
+  messages: InjectedMessage[]
+): BaseMessage[] {
+  const converted: BaseMessage[] = [];
+  for (const msg of messages) {
+    if (isEmptyInjectedContent(msg.content)) {
+      continue;
+    }
+    const additional_kwargs: Record<string, unknown> = {
+      role: msg.role,
+    };
+    if (msg.isMeta != null) additional_kwargs.isMeta = msg.isMeta;
+    if (msg.source != null) additional_kwargs.source = msg.source;
+    if (msg.skillName != null) additional_kwargs.skillName = msg.skillName;
+
+    converted.push(
+      new HumanMessage({
+        content: toLangChainContent(msg.content),
+        additional_kwargs,
+      })
+    );
+  }
+  return converted;
+}