@librechat/agents 3.3.3 → 3.3.5

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

@@ -1,5 +1,6 @@
 import { HumanMessage, AIMessage, ToolMessage } from '@langchain/core/messages';
 import type { TPayload } from '@/types';
+import { HARD_MAX_TOOL_RESULT_CHARS } from '@/utils/truncation';
 import { formatAgentMessages } from './format';
 import { ContentTypes } from '@/common';
 
@@ -38,6 +39,108 @@ describe('formatAgentMessages with tools parameter', () => {
     expect((result.messages[2] as ToolMessage).tool_call_id).toBe('123');
   });
 
+  it('restores persisted structured tool output for harness accounting', () => {
+    const output = [
+      {
+        type: ContentTypes.TEXT,
+        text: JSON.stringify([
+          { id: 1, value: 'first' },
+          { id: 2, value: 'second' },
+        ]),
+      },
+    ];
+    const payload: TPayload = [
+      { role: 'user', content: 'Query the table' },
+      {
+        role: 'assistant',
+        content: [
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'query-1',
+              name: 'run_select_query',
+              args: '{}',
+              output,
+            },
+          },
+        ],
+      },
+    ];
+
+    const result = formatAgentMessages(payload, { 0: 5, 1: 0 });
+
+    const toolMessage = result.messages[2] as ToolMessage;
+    expect(toolMessage).toBeInstanceOf(ToolMessage);
+    expect(toolMessage.content).toEqual(output);
+    expect(toolMessage.tool_call_id).toBe('query-1');
+  });
+
+  it('normalizes opaque persisted tool output before provider dispatch', () => {
+    const output = [{ type: 'json', rows: [{ id: 1, value: 'first' }] }];
+    const payload: TPayload = [
+      { role: 'user', content: 'Query the table' },
+      {
+        role: 'assistant',
+        content: [
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'query-opaque',
+              name: 'run_select_query',
+              args: '{}',
+              output,
+            },
+          },
+        ],
+      },
+    ];
+
+    const result = formatAgentMessages(payload);
+    const toolMessage = result.messages[2] as ToolMessage;
+
+    expect(typeof toolMessage.content).toBe('string');
+    expect(toolMessage.content).toBe(JSON.stringify(output));
+  });
+
+  it('hard-caps persisted structured output without invoking toJSON', () => {
+    let toJSONCalls = 0;
+    const output = {
+      rows: [{ value: 'x'.repeat(HARD_MAX_TOOL_RESULT_CHARS + 1_000) }],
+      toJSON() {
+        toJSONCalls++;
+        return 'y'.repeat(HARD_MAX_TOOL_RESULT_CHARS * 2);
+      },
+    };
+    const payload: TPayload = [
+      { role: 'user', content: 'Query the table' },
+      {
+        role: 'assistant',
+        content: [
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'query-bounded',
+              name: 'run_select_query',
+              args: '{}',
+              output,
+            },
+          },
+        ],
+      },
+    ];
+
+    const result = formatAgentMessages(payload);
+    const content = (result.messages[2] as ToolMessage).content;
+
+    expect(toJSONCalls).toBe(0);
+    expect(typeof content).toBe('string');
+    expect((content as string).length).toBeLessThanOrEqual(
+      HARD_MAX_TOOL_RESULT_CHARS
+    );
+    expect(content).toContain('truncated');
+    expect(content).not.toContain('y'.repeat(1_000));
+  });
+
   it('should filter out all tool calls when tools set is empty', () => {
     const payload: TPayload = [
       { role: 'user', content: 'What\'s the weather?' },

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;
+}