@librechat/agents 3.2.34 → 3.2.36

package/src/graphs/Graph.ts

@@ -23,7 +23,9 @@ import {
   formatArtifactPayload,
   enforceOriginalContentCap,
   formatContentStrings,
+  isLegacyConvertible,
   createPruneMessages,
+  syncBudgetDerivedFields,
   addCacheControl,
   getMessageId,
   makeIsDeferred,
@@ -45,6 +47,7 @@ import {
   isAnthropicLike,
   isOpenAILike,
   isGoogleLike,
+  apportionTokenCounts,
   joinKeys,
   sleep,
 } from '@/utils';
@@ -89,6 +92,26 @@ const { AGENT, TOOLS, SUMMARIZE } = GraphNodeKeys;
 /** Minimum relative variance before calibrated toolSchemaTokens overrides current value. */
 const CALIBRATION_VARIANCE_THRESHOLD = 0.15;
 
+/**
+ * Start index of the span post-prune formatters can mutate in place: the
+ * trailing tool batch plus its owning AI message (artifact formatting touches
+ * every tool result after the last AI tool call; Bedrock rewrites the AI
+ * message before a trailing tool result). Capped so the usage-snapshot
+ * recount stays constant-cost.
+ */
+function trailingMutationStart(messages: BaseMessage[]): number {
+  const MAX_SPAN = 16;
+  let index = messages.length - 1;
+  while (
+    index >= 0 &&
+    messages[index]?.getType() === 'tool' &&
+    messages.length - index < MAX_SPAN
+  ) {
+    index--;
+  }
+  return Math.max(0, Math.min(index, messages.length - 2));
+}
+
 type ReasoningKey = 'reasoning_content' | 'reasoning';
 type ReasoningSummary = { summary?: Array<{ text?: string }> };
 type ReasoningDetail = { type?: string; text?: string };
@@ -825,6 +848,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   agentContexts: Map<string, AgentContext> = new Map();
   /** Default agent ID to use */
   defaultAgentId: string;
+  /**
+   * Host sink for model usage emitted inside subagent child runs. Threaded
+   * into each `SubagentExecutor` this graph creates (and from there into
+   * child graphs, so nested subagents report too). See
+   * {@link t.StandardGraphInput.subagentUsageSink}.
+   */
+  subagentUsageSink?: t.SubagentUsageSink;
 
   constructor({
     runId,
@@ -834,11 +864,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     tokenCounter,
     indexTokenCountMap,
     calibrationRatio,
+    subagentUsageSink,
   }: t.StandardGraphInput) {
     super();
     this.runId = runId;
     this.signal = signal;
     this.langfuse = langfuse;
+    this.subagentUsageSink = subagentUsageSink;
 
     if (agents.length === 0) {
       throw new Error('At least one agent configuration is required');
@@ -1423,6 +1455,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       this.config = config;
 
       let messagesToUse = messages;
+      let contextUsage: t.ContextUsageEvent | null = null;
       if (
         !agentContext.pruneMessages &&
         agentContext.tokenCounter &&
@@ -1462,6 +1495,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           originalToolContent,
           calibrationRatio,
           resolvedInstructionOverhead,
+          contextBudget,
+          effectiveInstructionTokens,
         } = agentContext.pruneMessages({
           messages,
           usageMetadata: agentContext.currentUsage,
@@ -1489,10 +1524,42 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               : 1;
           if (variance > CALIBRATION_VARIANCE_THRESHOLD) {
             agentContext.toolSchemaTokens = calibratedToolTokens;
+            /** Largest-remainder apportionment keeps the per-tool breakdown
+             *  summing exactly to the calibrated aggregate */
+            if (agentContext.toolTokenCounts != null && currentToolTokens > 0) {
+              agentContext.toolTokenCounts = apportionTokenCounts(
+                agentContext.toolTokenCounts,
+                calibratedToolTokens / currentToolTokens,
+                calibratedToolTokens
+              );
+            }
           }
         }
         messagesToUse = context;
 
+        /** Dispatched right before the model invoke — a summarization
+         *  detour returns from this node without an LLM call, and the
+         *  post-summary retry produces its own snapshot.
+         *
+         *  The breakdown describes the post-prune prompt: counts from the
+         *  kept context, message tokens derived from the same calibrated
+         *  budget math as `remainingContextTokens` (the index map is keyed
+         *  by pre-prune state indices, so summing it over `context` would
+         *  missum); `prePruneContextTokens` carries the pre-prune metric. */
+        const usageBreakdown = agentContext.getTokenBudgetBreakdown(messages);
+        usageBreakdown.messageCount = context.length;
+        contextUsage = {
+          runId: this.runId,
+          agentId,
+          breakdown: usageBreakdown,
+          contextBudget,
+          effectiveInstructionTokens,
+          prePruneContextTokens,
+          remainingContextTokens,
+          calibrationRatio: agentContext.calibrationRatio,
+        };
+        syncBudgetDerivedFields(contextUsage);
+
         const hasPrunedMessages =
           agentContext.summarizationEnabled === true &&
           Array.isArray(messagesToRefine) &&
@@ -1598,6 +1665,33 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       }
 
       let finalMessages = messagesToUse;
+      /** Tail snapshot for the dispatch-time usage delta: in-place
+       *  formatters (artifact appends, Bedrock content rewrites, legacy
+       *  string conversion) mutate without changing length or identity —
+       *  capture before they run. Legacy string conversion can also touch
+       *  messages before the tail, so those convertible indices are
+       *  tracked separately (none exist in the common case). */
+      const tailStart = trailingMutationStart(messagesToUse);
+      let preFormatTailTokens: number | null = null;
+      let legacyIndices: number[] | null = null;
+      let preFormatLegacyTokens = 0;
+      if (contextUsage != null && agentContext.tokenCounter != null) {
+        preFormatTailTokens = 0;
+        for (const message of messagesToUse.slice(tailStart)) {
+          preFormatTailTokens += agentContext.tokenCounter(message);
+        }
+        if (agentContext.useLegacyContent) {
+          legacyIndices = [];
+          for (let i = 0; i < tailStart; i++) {
+            if (isLegacyConvertible(messagesToUse[i])) {
+              legacyIndices.push(i);
+              preFormatLegacyTokens += agentContext.tokenCounter(
+                messagesToUse[i]
+              );
+            }
+          }
+        }
+      }
       if (agentContext.useLegacyContent) {
         finalMessages = formatContentStrings(finalMessages);
       }
@@ -1788,6 +1882,79 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         );
       }
 
+      /** Past the empty-prompt guard — a model call is now guaranteed */
+      if (contextUsage != null) {
+        const usageRatio =
+          contextUsage.calibrationRatio != null &&
+          contextUsage.calibrationRatio > 0
+            ? contextUsage.calibrationRatio
+            : 1;
+        if (
+          agentContext.tokenCounter != null &&
+          finalMessages.length !== messagesToUse.length
+        ) {
+          /** Post-prune formatting restructured the payload (e.g. thinking
+           *  placeholder collapse, orphan drops) — recount so the gauge
+           *  reflects what is actually sent */
+          let rawTokens = 0;
+          for (const message of finalMessages) {
+            rawTokens += agentContext.tokenCounter(message);
+          }
+          contextUsage.breakdown.messageCount = finalMessages.length;
+          if (
+            contextUsage.contextBudget != null &&
+            contextUsage.effectiveInstructionTokens != null
+          ) {
+            contextUsage.remainingContextTokens = Math.max(
+              0,
+              contextUsage.contextBudget -
+                contextUsage.effectiveInstructionTokens -
+                Math.round(rawTokens * usageRatio)
+            );
+          }
+        } else if (
+          preFormatTailTokens != null &&
+          agentContext.tokenCounter != null &&
+          contextUsage.remainingContextTokens != null
+        ) {
+          /** Same-length formatting can still mutate in place — the trailing
+           *  tool batch (artifacts, Bedrock rewrites) and any legacy-converted
+           *  messages before it — adjust remaining by the calibrated delta */
+          let postFormatTailTokens = 0;
+          for (const message of finalMessages.slice(tailStart)) {
+            postFormatTailTokens += agentContext.tokenCounter(message);
+          }
+          let formatDelta = postFormatTailTokens - preFormatTailTokens;
+          if (legacyIndices != null && legacyIndices.length > 0) {
+            let postFormatLegacyTokens = 0;
+            for (const index of legacyIndices) {
+              postFormatLegacyTokens += agentContext.tokenCounter(
+                finalMessages[index]
+              );
+            }
+            formatDelta += postFormatLegacyTokens - preFormatLegacyTokens;
+          }
+          if (formatDelta !== 0) {
+            contextUsage.remainingContextTokens = Math.max(
+              0,
+              Math.min(
+                contextUsage.contextBudget ?? Number.MAX_SAFE_INTEGER,
+                contextUsage.remainingContextTokens -
+                  Math.round(formatDelta * usageRatio)
+              )
+            );
+          }
+        }
+        syncBudgetDerivedFields(contextUsage);
+        /** Awaited so async host handlers receive the pre-invoke snapshot
+         *  before any model deltas are emitted */
+        await safeDispatchCustomEvent(
+          GraphEvents.ON_CONTEXT_USAGE,
+          contextUsage,
+          config
+        );
+      }
+
       const invokeStart = Date.now();
       const invokeMeta = { runId: this.runId, agentId };
       emitAgentLog(
@@ -2063,6 +2230,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           parentAgentId: agentContext.agentId,
           langfuse: this.langfuse,
           tokenCounter: agentContext.tokenCounter,
+          usageSink: this.subagentUsageSink,
           maxDepth: effectiveSubagentDepth,
           createChildGraph: (input): StandardGraph => {
             const childGraph = new StandardGraph(input);

package/src/index.ts

@@ -8,6 +8,9 @@ export * from './messages';
 /* Graphs */
 export * from './graphs';
 
+/* Context-usage projection (host-side pre-send snapshot) */
+export * from './agents/projection';
+
 /* Summarization */
 export * from './summarization';
 

package/src/llm/anthropic/utils/cross-provider-reasoning.test.ts

@@ -0,0 +1,317 @@
+import { AIMessage, HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import { _convertMessagesToAnthropicPayload } from './message_inputs';
+
+/**
+ * Regression for cross-provider agent handoffs (e.g. Bedrock → Anthropic): a
+ * Bedrock turn that used extended thinking leaves a `reasoning_content` content
+ * block ({ reasoningText: { text, signature } }) in the history. The official
+ * Anthropic converter has no branch for it and previously threw
+ * "Unsupported message content format", crashing the handoff. Only known
+ * foreign reasoning (Bedrock `reasoning_content`, Google `reasoning`, LibreChat
+ * `think`) is dropped; any other unknown block still throws rather than being
+ * silently omitted (real content — user media, Google code-execution — must be
+ * surfaced); and a tool call carried only on `tool_calls` survives dropping its
+ * reasoning sibling without being duplicated.
+ */
+type AnthropicPayload = ReturnType<typeof _convertMessagesToAnthropicPayload>;
+
+/** Minimal view of a converted Anthropic content block the assertions read. */
+interface TestBlock {
+  type?: string;
+  text?: string;
+}
+
+const findAssistant = (payload: AnthropicPayload) =>
+  payload.messages.find((m) => m.role === 'assistant');
+
+const assistantBlocks = (payload: AnthropicPayload): TestBlock[] => {
+  const content = findAssistant(payload)?.content;
+  return Array.isArray(content) ? (content as TestBlock[]) : [];
+};
+
+describe('_convertMessagesToAnthropicPayload — cross-provider reasoning blocks', () => {
+  const bedrockHandoffHistory = (): BaseMessage[] => [
+    new HumanMessage('research Assort Health'),
+    new AIMessage({
+      content: [
+        {
+          type: 'reasoning_content',
+          index: 0,
+          reasoningText: {
+            text: 'Let me search Notion then hand off to the data agent.',
+            signature: 'bedrock-signature-not-valid-for-anthropic',
+          },
+        },
+        { type: 'text', text: 'Kicking off the searches now.' },
+        {
+          type: 'tool_use',
+          id: 'tooluse_abc',
+          name: 'notion-search',
+          input: { query: 'Assort Health' },
+        },
+      ],
+      tool_calls: [
+        {
+          id: 'tooluse_abc',
+          name: 'notion-search',
+          args: { query: 'Assort Health' },
+          type: 'tool_call',
+        },
+      ],
+    }),
+  ];
+
+  it('does not throw on a Bedrock reasoning_content block', () => {
+    expect(() =>
+      _convertMessagesToAnthropicPayload(bedrockHandoffHistory())
+    ).not.toThrow();
+  });
+
+  it('drops reasoning_content (incl. its foreign signature) but keeps text and tool_use', () => {
+    const payload = _convertMessagesToAnthropicPayload(bedrockHandoffHistory());
+    expect(findAssistant(payload)).toBeDefined();
+    const blocks = assistantBlocks(payload);
+
+    expect(blocks.find((b) => b.type === 'reasoning_content')).toBeUndefined();
+    expect(
+      blocks.find(
+        (b) => b.type === 'thinking' || b.type === 'redacted_thinking'
+      )
+    ).toBeUndefined();
+    expect(JSON.stringify(blocks)).not.toContain(
+      'bedrock-signature-not-valid-for-anthropic'
+    );
+
+    expect(
+      blocks.some(
+        (b) => b.type === 'text' && b.text === 'Kicking off the searches now.'
+      )
+    ).toBe(true);
+    expect(blocks.find((b) => b.type === 'tool_use')).toMatchObject({
+      type: 'tool_use',
+      id: 'tooluse_abc',
+      name: 'notion-search',
+      input: { query: 'Assort Health' },
+    });
+  });
+
+  it('drops a Google `reasoning` block without throwing', () => {
+    const history: BaseMessage[] = [
+      new HumanMessage('hi'),
+      new AIMessage({
+        content: [
+          { type: 'reasoning', reasoning: 'internal google chain of thought' },
+          { type: 'text', text: 'Hello!' },
+        ],
+      }),
+    ];
+    expect(() => _convertMessagesToAnthropicPayload(history)).not.toThrow();
+    const blocks = assistantBlocks(_convertMessagesToAnthropicPayload(history));
+    expect(blocks.find((b) => b.type === 'reasoning')).toBeUndefined();
+    expect(blocks.some((b) => b.type === 'text' && b.text === 'Hello!')).toBe(
+      true
+    );
+  });
+
+  it('drops a LibreChat `think` block without throwing', () => {
+    const history: BaseMessage[] = [
+      new HumanMessage('hi'),
+      new AIMessage({
+        content: [
+          { type: 'think', think: 'librechat serialized reasoning' },
+          { type: 'text', text: 'Done.' },
+        ],
+      }),
+    ];
+    expect(() => _convertMessagesToAnthropicPayload(history)).not.toThrow();
+    const blocks = assistantBlocks(_convertMessagesToAnthropicPayload(history));
+    expect(blocks.find((b) => b.type === 'think')).toBeUndefined();
+    expect(blocks.some((b) => b.type === 'text' && b.text === 'Done.')).toBe(
+      true
+    );
+  });
+
+  it('drops an unsigned `thinking` block (Google thinking-enabled output) on an assistant turn', () => {
+    const history: BaseMessage[] = [
+      new HumanMessage('hi'),
+      new AIMessage({
+        content: [
+          {
+            type: 'thinking',
+            thinking: 'google chain of thought, no signature',
+          },
+          { type: 'text', text: 'Answer.' },
+        ],
+      }),
+    ];
+    expect(() => _convertMessagesToAnthropicPayload(history)).not.toThrow();
+    const blocks = assistantBlocks(_convertMessagesToAnthropicPayload(history));
+    expect(blocks.find((b) => b.type === 'thinking')).toBeUndefined();
+    expect(blocks.some((b) => b.type === 'text' && b.text === 'Answer.')).toBe(
+      true
+    );
+  });
+
+  it('forwards a signed `thinking` block (Anthropic-native) unchanged', () => {
+    const history: BaseMessage[] = [
+      new HumanMessage('hi'),
+      new AIMessage({
+        content: [
+          {
+            type: 'thinking',
+            thinking: 'native reasoning',
+            signature: 'valid-sig',
+          },
+          { type: 'text', text: 'Answer.' },
+        ],
+      }),
+    ];
+    const blocks = assistantBlocks(_convertMessagesToAnthropicPayload(history));
+    expect(blocks.find((b) => b.type === 'thinking')).toMatchObject({
+      type: 'thinking',
+      thinking: 'native reasoning',
+      signature: 'valid-sig',
+    });
+  });
+
+  it('throws (not silently drops) on an unknown assistant block such as Google code execution', () => {
+    // executableCode/codeExecutionResult carry real visible content; silently
+    // dropping them on a Google → Anthropic handoff would lose evidence.
+    const history: BaseMessage[] = [
+      new HumanMessage('run some code'),
+      new AIMessage({
+        content: [
+          {
+            type: 'executableCode',
+            executableCode: { language: 'PYTHON', code: 'print(2+2)' },
+          },
+          { type: 'text', text: 'Here is the result.' },
+        ],
+      }),
+    ];
+    expect(() => _convertMessagesToAnthropicPayload(history)).toThrow(
+      'Unsupported message content format'
+    );
+  });
+
+  it('throws (not silently drops) on an unsupported user block such as media', () => {
+    const history: BaseMessage[] = [
+      new HumanMessage({
+        content: [
+          {
+            type: 'video_url',
+            video_url: { url: 'https://example.com/v.mp4' },
+          },
+          { type: 'text', text: 'what is in this video?' },
+        ],
+      }),
+    ];
+    expect(() => _convertMessagesToAnthropicPayload(history)).toThrow(
+      'Unsupported message content format'
+    );
+  });
+
+  it('does not drop a reasoning-typed block on a user turn (only assistant reasoning is dropped)', () => {
+    const history: BaseMessage[] = [
+      new HumanMessage({
+        content: [
+          { type: 'reasoning_content', reasoningText: { text: 'user text' } },
+          { type: 'text', text: 'hello' },
+        ],
+      }),
+    ];
+    expect(() => _convertMessagesToAnthropicPayload(history)).toThrow(
+      'Unsupported message content format'
+    );
+  });
+
+  it('preserves a tool call carried only on tool_calls when its reasoning sibling is dropped', () => {
+    // Mirrors a Bedrock extended-thinking turn: the tool lives only on
+    // `tool_calls`; `content` holds just the reasoning block (no tool_use).
+    const history: BaseMessage[] = [
+      new HumanMessage('research Assort Health'),
+      new AIMessage({
+        content: [
+          {
+            type: 'reasoning_content',
+            reasoningText: { text: 'I should hand off now.', signature: 'sig' },
+          },
+        ],
+        tool_calls: [
+          {
+            id: 'tooluse_transfer',
+            name: 'lc_transfer_to_data_agent',
+            args: { reason: 'need consumption data' },
+            type: 'tool_call',
+          },
+        ],
+      }),
+    ];
+    expect(() => _convertMessagesToAnthropicPayload(history)).not.toThrow();
+    const blocks = assistantBlocks(_convertMessagesToAnthropicPayload(history));
+    expect(blocks.find((b) => b.type === 'reasoning_content')).toBeUndefined();
+    expect(blocks.find((b) => b.type === 'tool_use')).toMatchObject({
+      type: 'tool_use',
+      id: 'tooluse_transfer',
+      name: 'lc_transfer_to_data_agent',
+      input: { reason: 'need consumption data' },
+    });
+    // The `_` placeholder must not linger once a real tool_use block is present.
+    expect(blocks.some((b) => b.type === 'text' && b.text === '_')).toBe(false);
+  });
+
+  it('does not duplicate a Google functionCall tool call already materialized by _formatContent', () => {
+    // _formatContent converts the `functionCall` part into a tool_use; the
+    // materialization must recognize it as represented and not append a second.
+    const history: BaseMessage[] = [
+      new HumanMessage('weather in SF?'),
+      new AIMessage({
+        content: [
+          {
+            type: 'functionCall',
+            functionCall: { name: 'get_weather', args: { city: 'SF' } },
+          },
+        ],
+        tool_calls: [
+          {
+            id: 'call_weather_1',
+            name: 'get_weather',
+            args: { city: 'SF' },
+            type: 'tool_call',
+          },
+        ],
+      }),
+    ];
+    const blocks = assistantBlocks(_convertMessagesToAnthropicPayload(history));
+    const toolUses = blocks.filter((b) => b.type === 'tool_use');
+    expect(toolUses).toHaveLength(1);
+    expect(toolUses[0]).toMatchObject({
+      type: 'tool_use',
+      id: 'call_weather_1',
+      name: 'get_weather',
+    });
+  });
+
+  it('falls back to placeholder text when reasoning was the only content', () => {
+    const history: BaseMessage[] = [
+      new HumanMessage('hi'),
+      new AIMessage({
+        content: [
+          {
+            type: 'reasoning_content',
+            reasoningText: {
+              text: 'only thinking, no visible text',
+              signature: 'sig',
+            },
+          },
+        ],
+      }),
+    ];
+    expect(() => _convertMessagesToAnthropicPayload(history)).not.toThrow();
+    const blocks = assistantBlocks(_convertMessagesToAnthropicPayload(history));
+    expect(blocks.find((b) => b.type === 'reasoning_content')).toBeUndefined();
+    expect(blocks.length).toBeGreaterThan(0);
+    expect(blocks.every((b) => b.type === 'text')).toBe(true);
+  });
+});