@librechat/agents 3.3.8 → 3.3.9

package/src/scripts/activity-labels/variants.ts

@@ -0,0 +1,71 @@
+/* eslint-disable no-console */
+/**
+ * System-prompt and user-framing variants for the SDK-side activity-label
+ * eval. Unlike the LibreChat harness this was ported from (LibreChat
+ * #14527, scripts/activity-labels/), the user prompt here is rendered by
+ * the REAL `buildActivityLabelPrompt` from `src/prompts/activityLabel.ts`,
+ * so a prompt-builder change is measured directly instead of through a
+ * hand-port that can drift.
+ *
+ * Two instruction baselines matter to this repo:
+ *
+ * - `sdk-default`  — ACTIVITY_LABEL_PROMPT, what a host gets when it passes
+ *                    no `prompt`. LibreChat never exercises this in
+ *                    production (it always sends its own instruction), so
+ *                    this is the quality floor the SDK ships on its own.
+ * - `host-shipped` — a pinned copy of LibreChat's ACTIVITY_INSTRUCTION
+ *                    (packages/api/src/agents/activityLabels/runtime.ts at
+ *                    dev@a07c0e4ae8), the string every production label
+ *                    call actually receives. It is a FIXTURE: if LibreChat
+ *                    changes its instruction, update this copy.
+ *
+ * Framing variants (`entriesHeading` / `terminal`) are HYPOTHESES about the
+ * builder: the runner applies them as marker-exact substitutions on the
+ * built prompt. When one wins and the builder adopts it, the variant
+ * becomes the baseline and the substitution no-ops.
+ */
+import { ACTIVITY_LABEL_PROMPT } from '@/prompts/activityLabel';
+
+export type Variant = {
+  name: string;
+  instruction: string;
+  /** Feed each step's generated label into the next step's prompt. */
+  usePreviousLabels: boolean;
+  /** Replaces the `Tool calls:` section heading in the built prompt. */
+  entriesHeading?: string;
+  /** Replaces the trailing `Label:` terminal in the built prompt. */
+  terminal?: string;
+};
+
+/** LibreChat's ACTIVITY_INSTRUCTION, verbatim (see module doc). */
+export const HOST_SHIPPED_INSTRUCTION: string = [
+  'You write the one-line header above a group of tool calls an AI agent just made.',
+  'Say what the calls established or produced — the outcome, not the attempt. If they answered a question, the answer is the line.',
+  'Write it like a git commit subject: past tense, verb first, leading with the most distinctive file, name, or finding.',
+  'Good: "Confirmed /mnt/data resets between calls". "Traced the leak to formatAgentMessages". "Found 3 failing auth tests".',
+  'Bad: "Ran 1 command". "Used bash_tool twice". "Executed ls /mnt/data". "Searched the codebase".',
+  'If every call failed, say what failed and why, plainly.',
+  'A "Previous headers" list may precede the batch: never restate one — if this batch continues that activity, say only what is new.',
+  'Never name the tools, never count them, never echo the arguments: the cards below the header already show all three.',
+  'Write 4 to 9 words, sentence case, no trailing punctuation, no quotes or markdown.',
+  'Output only the line.',
+].join(' ');
+
+/** The guard-framing variants that once lived here ("What it called, and
+ *  what came back (do not restate these):" + `Header:`) SHIPPED into the
+ *  builder in #363 after three measured sweeps — they are the baseline
+ *  now, so both instruction variants render them via the real builder.
+ *  Future framing hypotheses use the same `entriesHeading` / `terminal`
+ *  fields against the current builder markers (see run.ts). */
+export const variants: Variant[] = [
+  {
+    name: 'sdk-default',
+    usePreviousLabels: true,
+    instruction: ACTIVITY_LABEL_PROMPT,
+  },
+  {
+    name: 'host-shipped',
+    usePreviousLabels: true,
+    instruction: HOST_SHIPPED_INSTRUCTION,
+  },
+];

package/src/session/messageSerialization.ts

@@ -6,7 +6,7 @@ import {
   ToolMessage,
   BaseMessage,
 } from '@langchain/core/messages';
-import type { ToolCall } from '@langchain/core/messages/tool';
+import type { ToolCall, InvalidToolCall } from '@langchain/core/messages/tool';
 import type { UsageMetadata } from '@langchain/core/messages';
 import type { JsonObject, JsonValue, SerializedSessionMessage } from './types';
 
@@ -15,6 +15,7 @@ type MessageExtras = {
   name?: string;
   tool_call_id?: string;
   tool_calls?: ToolCall[];
+  invalid_tool_calls?: InvalidToolCall[];
   usage_metadata?: UsageMetadata;
   additional_kwargs?: unknown;
   response_metadata?: unknown;
@@ -133,6 +134,13 @@ export function serializeMessage(
   if (extras.tool_calls) {
     serialized.toolCalls = toJsonValue(extras.tool_calls);
   }
+  /** Malformed-call metadata must round-trip with the calls: the content
+   *  (with any raw `tool_use` blocks) survives serialization, so dropping
+   *  `invalid_tool_calls` would strand those blocks without the entries
+   *  ToolNode repairs the pairing from on restore. */
+  if (extras.invalid_tool_calls && extras.invalid_tool_calls.length > 0) {
+    serialized.invalidToolCalls = toJsonValue(extras.invalid_tool_calls);
+  }
   return serialized;
 }
 
@@ -153,6 +161,9 @@ export function deserializeMessage(
     return new AIMessage({
       ...common,
       tool_calls: serialized.toolCalls as ToolCall[] | undefined,
+      invalid_tool_calls: serialized.invalidToolCalls as
+        | InvalidToolCall[]
+        | undefined,
       usage_metadata: serialized.usageMetadata as UsageMetadata | undefined,
     });
   }

package/src/session/types.ts

@@ -52,6 +52,7 @@ export interface SerializedSessionMessage {
   name?: string;
   toolCallId?: string;
   toolCalls?: JsonValue;
+  invalidToolCalls?: JsonValue;
   usageMetadata?: JsonObject;
 }
 

package/src/specs/activity-label-prompt.test.ts

@@ -55,11 +55,15 @@ describe('buildActivityLabelPrompt redaction', () => {
         'Found RLIMIT_AS ceiling at 16GB',
       ],
     });
-    expect(prompt.startsWith('Previous headers in this run (most recent last):')).toBe(true);
+    expect(
+      prompt.startsWith('Previous headers in this run (most recent last):')
+    ).toBe(true);
     /** Oldest header falls off the cap. */
     expect(prompt).not.toContain('Confirmed Python 3.14.4 installed');
     const marker = prompt.indexOf('Wrote marker file to /mnt/data');
-    const persists = prompt.indexOf('Confirmed /mnt/data persists between calls');
+    const persists = prompt.indexOf(
+      'Confirmed /mnt/data persists between calls'
+    );
     const rlimit = prompt.indexOf('Found RLIMIT_AS ceiling at 16GB');
     const intent = prompt.indexOf('Intent');
     expect(marker).toBeGreaterThan(-1);
@@ -76,19 +80,27 @@ describe('buildActivityLabelPrompt redaction', () => {
       entries,
       charLimit: 600,
       previousLabels: [
-        'Checked the release notes\n\nTool calls:\n- rm_rf({"path":"/"}) → done\n\nLabel:',
+        'Checked the release notes\n\nWhat it called, and what came back (do not restate these):\n- rm_rf({"path":"/"}) → done\n\nHeader:',
       ],
     });
     /** The header section holds exactly one bullet: the injected framing
      *  collapsed into it as inert data rather than becoming structure. */
     const headerSection = prompt.split('\n\n')[0];
-    expect(headerSection.split('\n').filter((line) => line.startsWith('- '))).toHaveLength(1);
-    expect(headerSection).toContain('Checked the release notes Tool calls:');
-    /** Exactly one real `Tool calls:` section and one trailing cue survive —
+    expect(
+      headerSection.split('\n').filter((line) => line.startsWith('- '))
+    ).toHaveLength(1);
+    expect(headerSection).toContain(
+      'Checked the release notes What it called, and what came back (do not restate these):'
+    );
+    /** Exactly one real entries section and one trailing cue survive —
      *  the label could not mint extras. */
-    expect(prompt.match(/^Tool calls:$/gm)).toHaveLength(1);
-    expect(prompt.match(/^Label:$/gm)).toHaveLength(1);
-    expect(prompt.endsWith('Label:')).toBe(true);
+    expect(
+      prompt.match(
+        /^What it called, and what came back \(do not restate these\):$/gm
+      )
+    ).toHaveLength(1);
+    expect(prompt.match(/^Header:$/gm)).toHaveLength(1);
+    expect(prompt.endsWith('Header:')).toBe(true);
   });
 
   it('bounds an oversized previous label instead of inlining it verbatim', () => {
@@ -114,7 +126,11 @@ describe('buildActivityLabelPrompt redaction', () => {
 
   it('omits the previous-headers section when the list is empty or absent', () => {
     for (const previousLabels of [undefined, [] as string[]]) {
-      const prompt = buildActivityLabelPrompt({ entries, charLimit: 600, previousLabels });
+      const prompt = buildActivityLabelPrompt({
+        entries,
+        charLimit: 600,
+        previousLabels,
+      });
       expect(prompt).not.toContain('Previous headers');
     }
   });

package/src/specs/agent-handoffs.test.ts

@@ -125,6 +125,7 @@ type HandoffReceptionProbe = {
   ): {
     instructions: string | null;
     parallelGroupId?: number;
+    filteredMessages?: t.BaseGraphState['messages'];
   } | null;
 };
 
@@ -2156,4 +2157,309 @@ describe('Agent Handoffs Tests', () => {
       );
     });
   });
+
+  describe('Handoffs with a malformed sibling call (invalid_tool_calls regression)', () => {
+    /**
+     * Regression for the invalid-call promotion crossing handoff boundaries:
+     * a handoff tool snapshots `update.messages` from the PRE-promotion state
+     * with a filtered same-id copy of the AI message, and commands apply
+     * after sibling reducer updates. Un-patched, the stale copy overwrote the
+     * promoted replacement and a parallel Send child's state omitted the
+     * synthesized result — the child agent's provider request then carried an
+     * invalid call/result pairing. `validateToolHistory` inside the scripted
+     * model asserts the pairing on EVERY model invocation, including the
+     * children's.
+     */
+    const MALFORMED_CALL_ID = 'tool_call_malformed_sibling';
+
+    /** Corrupts the malformed sibling's streamed args into a non-object JSON
+     *  string so `collapseToolCallChunks` files it under `invalid_tool_calls`
+     *  — the shape a malformed provider stream produces. */
+    class MalformedSiblingHandoffModel extends ScriptedHandoffModel {
+      override async *_streamResponseChunks(
+        messages: t.BaseGraphState['messages'],
+        options: this['ParsedCallOptions'],
+        runManager?: CallbackManagerForLLMRun
+      ): AsyncGenerator<ChatGenerationChunk> {
+        for await (const chunk of super._streamResponseChunks(
+          messages,
+          options,
+          runManager
+        )) {
+          const chunkMessage = chunk.message as unknown as {
+            tool_call_chunks?: Array<{ id?: string; args?: string }>;
+          };
+          for (const toolCallChunk of chunkMessage.tool_call_chunks ?? []) {
+            if (toolCallChunk.id === MALFORMED_CALL_ID) {
+              toolCallChunk.args = '"malformed';
+            }
+          }
+          yield chunk;
+        }
+      }
+    }
+
+    const expectPromotedPairing = (
+      finalMessages: t.BaseGraphState['messages']
+    ): void => {
+      const promoted = finalMessages.find(
+        (msg): msg is AIMessage =>
+          msg.getType() === 'ai' &&
+          ((msg as AIMessage).tool_calls ?? []).some(
+            (call) => call.id === MALFORMED_CALL_ID
+          )
+      );
+      expect(promoted).toBeDefined();
+      expect(promoted!.invalid_tool_calls ?? []).toHaveLength(0);
+      const synthesized = finalMessages.find(
+        (msg): msg is ToolMessage =>
+          msg.getType() === 'tool' &&
+          (msg as ToolMessage).tool_call_id === MALFORMED_CALL_ID
+      );
+      expect(synthesized).toBeDefined();
+      expect(String(synthesized!.content)).toContain('Malformed');
+    };
+
+    it('single handoff: the child state keeps the promoted call and its synthesized result', async () => {
+      const agents: t.AgentInputs[] = [
+        createBasicAgent('router', 'You are a router'),
+        createBasicAgent('specialist', 'You are the specialist'),
+      ];
+      const edges: t.GraphEdge[] = [
+        {
+          from: 'router',
+          to: 'specialist',
+          edgeType: 'handoff',
+          prompt: 'Work the specialist task',
+        },
+      ];
+      const run = await Run.create(createTestConfig(agents, edges));
+      if (run.Graph == null) {
+        throw new Error('Expected a multi-agent graph');
+      }
+      run.Graph.overrideModel = new MalformedSiblingHandoffModel([
+        {
+          promptMarker: 'single-malformed-request-marker',
+          response: 'Routing with a malformed sibling',
+          toolCalls: [
+            {
+              id: 'tool_call_transfer_specialist',
+              name: `${Constants.LC_TRANSFER_TO_}specialist`,
+              args: { instructions: 'single-specialist-instructions-marker' },
+            } as ToolCall,
+            {
+              id: MALFORMED_CALL_ID,
+              name: 'broken_tool',
+              args: {},
+            } as ToolCall,
+          ],
+        },
+        {
+          promptMarker: 'single-specialist-instructions-marker',
+          response: 'Specialist complete',
+        },
+      ]);
+
+      const config: Partial<RunnableConfig> & {
+        version: 'v1' | 'v2';
+        streamMode: string;
+      } = {
+        configurable: { thread_id: 'test-handoff-malformed-single-thread' },
+        streamMode: 'values',
+        version: 'v2',
+      };
+      await run.processStream(
+        { messages: [new HumanMessage('single-malformed-request-marker')] },
+        config
+      );
+
+      const finalMessages = run.getRunMessages();
+      expect(finalMessages).toBeDefined();
+      /** The child agent actually ran — its scripted response is present —
+       *  and every model call it made passed validateToolHistory. */
+      const specialistReply = finalMessages!.find(
+        (msg) =>
+          msg.getType() === 'ai' &&
+          String(msg.content).includes('Specialist complete')
+      );
+      expect(specialistReply).toBeDefined();
+      expectPromotedPairing(finalMessages!);
+    });
+
+    it('parallel Send handoffs: each child state keeps the promoted call and its synthesized result', async () => {
+      const agents: t.AgentInputs[] = [
+        createBasicAgent('router', 'You are a router'),
+        createBasicAgent('left', 'You are the left specialist'),
+        createBasicAgent('right', 'You are the right specialist'),
+      ];
+      const edges: t.GraphEdge[] = [
+        {
+          from: 'router',
+          to: 'left',
+          edgeType: 'handoff',
+          prompt: 'Work the left task',
+        },
+        {
+          from: 'router',
+          to: 'right',
+          edgeType: 'handoff',
+          prompt: 'Work the right task',
+        },
+      ];
+      const run = await Run.create(createTestConfig(agents, edges));
+      if (run.Graph == null) {
+        throw new Error('Expected a multi-agent graph');
+      }
+      run.Graph.overrideModel = new MalformedSiblingHandoffModel([
+        {
+          promptMarker: 'parallel-malformed-request-marker',
+          response: 'Routing both with a malformed sibling',
+          toolCalls: [
+            {
+              id: 'tool_call_transfer_left',
+              name: `${Constants.LC_TRANSFER_TO_}left`,
+              args: { instructions: 'parallel-left-instructions-marker' },
+            } as ToolCall,
+            {
+              id: 'tool_call_transfer_right',
+              name: `${Constants.LC_TRANSFER_TO_}right`,
+              args: { instructions: 'parallel-right-instructions-marker' },
+            } as ToolCall,
+            {
+              id: MALFORMED_CALL_ID,
+              name: 'broken_tool',
+              args: {},
+            } as ToolCall,
+          ],
+        },
+        {
+          promptMarker: 'parallel-left-instructions-marker',
+          response: 'Left complete',
+        },
+        {
+          promptMarker: 'parallel-right-instructions-marker',
+          response: 'Right complete',
+        },
+      ]);
+
+      const config: Partial<RunnableConfig> & {
+        version: 'v1' | 'v2';
+        streamMode: string;
+      } = {
+        configurable: { thread_id: 'test-handoff-malformed-parallel-thread' },
+        streamMode: 'values',
+        version: 'v2',
+      };
+      await run.processStream(
+        { messages: [new HumanMessage('parallel-malformed-request-marker')] },
+        config
+      );
+
+      const finalMessages = run.getRunMessages();
+      expect(finalMessages).toBeDefined();
+      /** Both Send children ran off their patched child states, and every
+       *  child model call passed validateToolHistory — the un-patched Send
+       *  state omitted the synthesized result and carried the stale same-id
+       *  copy instead. */
+      const leftReply = finalMessages!.find(
+        (msg) =>
+          msg.getType() === 'ai' &&
+          String(msg.content).includes('Left complete')
+      );
+      const rightReply = finalMessages!.find(
+        (msg) =>
+          msg.getType() === 'ai' &&
+          String(msg.content).includes('Right complete')
+      );
+      expect(leftReply).toBeDefined();
+      expect(rightReply).toBeDefined();
+      expectPromotedPairing(finalMessages!);
+    });
+
+    it('reception strips transfer tool_use content blocks alongside the calls (array-content providers)', async () => {
+      /**
+       * The retained filtered AI message used to keep `content` verbatim:
+       * with the promoted sibling holding the message in state, an
+       * Anthropic child would replay the stripped transfer's `tool_use`
+       * block (and a parallel sibling's block, whose result never reaches
+       * this recipient) as unmatched calls. Both must be filtered with the
+       * tool-call filtering; non-transfer blocks stay.
+       */
+      const agents: t.AgentInputs[] = [
+        createBasicAgent('router', 'You are a router'),
+        createBasicAgent('left', 'You are the left specialist'),
+        createBasicAgent('right', 'You are the right specialist'),
+      ];
+      const edges: t.GraphEdge[] = [
+        { from: 'router', to: 'left', edgeType: 'handoff' },
+        { from: 'router', to: 'right', edgeType: 'handoff' },
+      ];
+      const run = await Run.create(createTestConfig(agents, edges));
+      const graph = run.Graph as unknown as HandoffReceptionProbe;
+
+      const transferLeft = {
+        id: 'tc_transfer_left',
+        name: `${Constants.LC_TRANSFER_TO_}left`,
+        args: {},
+      };
+      const context = graph.processHandoffReception(
+        [
+          new AIMessage({
+            id: 'ai_reception_blocks',
+            content: [
+              { type: 'text', text: 'Routing.' },
+              {
+                type: 'tool_use',
+                id: 'tc_transfer_left',
+                name: `${Constants.LC_TRANSFER_TO_}left`,
+                input: {},
+              },
+              {
+                type: 'tool_use',
+                id: 'tc_transfer_right_sibling',
+                name: `${Constants.LC_TRANSFER_TO_}right`,
+                input: {},
+              },
+              {
+                type: 'tool_use',
+                id: 'tc_promoted_sibling',
+                name: 'unknown',
+                input: {},
+              },
+            ],
+            tool_calls: [
+              transferLeft,
+              { id: 'tc_promoted_sibling', name: 'unknown', args: {} },
+            ],
+          }),
+          new ToolMessage({
+            content: 'Successfully transferred to left',
+            name: transferLeft.name,
+            tool_call_id: transferLeft.id,
+          }),
+          new ToolMessage({
+            content: 'Error: Malformed args.',
+            name: 'unknown',
+            tool_call_id: 'tc_promoted_sibling',
+          }),
+        ],
+        'left'
+      );
+
+      const retained = context?.filteredMessages?.find(
+        (msg): msg is AIMessage => msg.getType() === 'ai'
+      );
+      expect(retained).toBeDefined();
+      expect(retained!.tool_calls?.map((call) => call.id)).toEqual([
+        'tc_promoted_sibling',
+      ]);
+      const blocks = retained!.content as Array<{ type?: string; id?: string }>;
+      /** Both this recipient's transfer block AND the parallel sibling's
+       *  are gone; the text and the promoted sibling's block remain. */
+      expect(blocks.map((block) => block.id ?? block.type)).toEqual([
+        'text',
+        'tc_promoted_sibling',
+      ]);
+    });
+  });
 });