@librechat/agents 3.2.34 → 3.2.35

package/src/specs/context-usage.live.test.ts

@@ -0,0 +1,297 @@
+// src/specs/context-usage.live.test.ts
+/**
+ * Live ON_CONTEXT_USAGE / usage accounting verification with real Anthropic
+ * calls — single agent, multi-agent handoff, and subagent isolation.
+ *
+ * Run with:
+ * RUN_CONTEXT_USAGE_LIVE_TESTS=1 ANTHROPIC_API_KEY=... npm test -- context-usage.live.test.ts --runInBand
+ */
+import { config as dotenvConfig } from 'dotenv';
+dotenvConfig();
+
+import { HumanMessage } from '@langchain/core/messages';
+import { describe, expect, it, jest } from '@jest/globals';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { createTokenCounter, TokenEncoderManager } from '@/utils/tokens';
+import { Constants, GraphEvents, Providers } from '@/common';
+import { ModelEndHandler } from '@/events';
+import { Run } from '@/run';
+
+const shouldRunLive =
+  process.env.RUN_CONTEXT_USAGE_LIVE_TESTS === '1' &&
+  process.env.ANTHROPIC_API_KEY != null &&
+  process.env.ANTHROPIC_API_KEY !== '';
+
+const describeIfLive = shouldRunLive ? describe : describe.skip;
+const modelName =
+  process.env.ANTHROPIC_CONTEXT_LIVE_MODEL ?? 'claude-haiku-4-5';
+
+const MAX_CONTEXT_TOKENS = 8000;
+
+function createAnthropicAgent(
+  agentId: string,
+  instructions: string,
+  extras: Partial<t.AgentInputs> = {}
+): t.AgentInputs {
+  return {
+    agentId,
+    provider: Providers.ANTHROPIC,
+    clientOptions: {
+      modelName,
+      apiKey: process.env.ANTHROPIC_API_KEY,
+      temperature: 0,
+      maxTokens: 128,
+      streaming: true,
+      streamUsage: true,
+    },
+    instructions,
+    maxContextTokens: MAX_CONTEXT_TOKENS,
+    ...extras,
+  };
+}
+
+function createStreamConfig(threadId: string): Partial<RunnableConfig> & {
+  version: 'v1' | 'v2';
+  streamMode: string;
+} {
+  return {
+    configurable: { thread_id: threadId },
+    streamMode: 'values',
+    version: 'v2',
+  };
+}
+
+interface CapturedEvents {
+  contextEvents: t.ContextUsageEvent[];
+  subagentUpdates: unknown[];
+  collectedUsage: Array<Record<string, number | undefined>>;
+  handlers: Record<string, t.EventHandler>;
+}
+
+function createCapture(): CapturedEvents {
+  const contextEvents: t.ContextUsageEvent[] = [];
+  const subagentUpdates: unknown[] = [];
+  const collectedUsage: Array<Record<string, number | undefined>> = [];
+  const handlers: Record<string, t.EventHandler> = {
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(collectedUsage as never),
+    [GraphEvents.ON_CONTEXT_USAGE]: {
+      handle: (_event, data): void => {
+        contextEvents.push(data as unknown as t.ContextUsageEvent);
+      },
+    },
+    [GraphEvents.ON_SUBAGENT_UPDATE]: {
+      handle: (_event, data): void => {
+        subagentUpdates.push(data);
+      },
+    },
+  };
+  return { contextEvents, subagentUpdates, collectedUsage, handlers };
+}
+
+describeIfLive('Context usage live integration', () => {
+  jest.setTimeout(180_000);
+
+  let tokenCounter: t.TokenCounter;
+
+  beforeAll(async () => {
+    tokenCounter = await createTokenCounter();
+  });
+
+  afterAll(() => {
+    TokenEncoderManager.reset();
+  });
+
+  it('emits a snapshot whose estimate tracks real provider input tokens', async () => {
+    const capture = createCapture();
+    const run = await Run.create<t.IState>({
+      runId: `ctx-live-single-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          createAnthropicAgent(
+            'solo',
+            'You are concise. Reply with one short sentence.'
+          ),
+        ],
+      },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers: capture.handlers,
+      tokenCounter,
+      indexTokenCountMap: {},
+    });
+
+    await run.processStream(
+      { messages: [new HumanMessage('Say hello in five words or fewer.')] },
+      createStreamConfig(`ctx-live-single-${Date.now()}`)
+    );
+
+    expect(capture.contextEvents).toHaveLength(1);
+    const event = capture.contextEvents[0];
+    expect(event.agentId).toBe('solo');
+    expect(event.breakdown.maxContextTokens).toBe(MAX_CONTEXT_TOKENS);
+    expect(event.contextBudget).toBeLessThanOrEqual(MAX_CONTEXT_TOKENS);
+
+    expect(capture.collectedUsage).toHaveLength(1);
+    const usage = capture.collectedUsage[0];
+    expect(usage.input_tokens ?? 0).toBeGreaterThan(0);
+    expect(usage.output_tokens ?? 0).toBeGreaterThan(0);
+
+    /** The gauge shows `contextBudget - remaining` as occupancy; with a real
+     *  tokenizer it should land in the same ballpark as the provider count */
+    const estimatedUsed =
+      (event.contextBudget ?? 0) - (event.remainingContextTokens ?? 0);
+    const providerInput = usage.input_tokens ?? 0;
+    expect(estimatedUsed).toBeGreaterThan(0);
+    expect(estimatedUsed / providerInput).toBeGreaterThan(0.3);
+    expect(estimatedUsed / providerInput).toBeLessThan(3);
+  });
+
+  it('emits per-agent snapshots and usage across a real handoff', async () => {
+    const capture = createCapture();
+    const nonce = `ctx-live-handoff-${Date.now()}`;
+    const expectedReply = `${nonce}-confirmed`;
+    const handoffToolName = `${Constants.LC_TRANSFER_TO_}specialist`;
+
+    const run = await Run.create<t.IState>({
+      runId: `${nonce}-run`,
+      graphConfig: {
+        type: 'multi-agent',
+        agents: [
+          createAnthropicAgent(
+            'router',
+            `You are a routing agent. For every user request, your only valid action is to call the handoff tool named ${handoffToolName}. Do not answer directly.
+
+When you call the handoff tool, include instructions telling the specialist to reply exactly with this marker and no extra words: ${expectedReply}`
+          ),
+          createAnthropicAgent(
+            'specialist',
+            'You are the specialist. When you receive handoff instructions with a marker, reply exactly with that marker and no extra words.'
+          ),
+        ],
+        edges: [
+          {
+            from: 'router',
+            to: 'specialist',
+            edgeType: 'handoff',
+            description: 'Transfer to the specialist for the final response',
+            prompt:
+              'Instructions for the specialist. Include any exact marker that must be returned.',
+            promptKey: 'instructions',
+          },
+        ],
+      },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers: capture.handlers,
+      tokenCounter,
+      indexTokenCountMap: {},
+    });
+
+    await run.processStream(
+      {
+        messages: [
+          new HumanMessage(
+            `Please delegate this to the specialist. The final answer must be exactly: ${expectedReply}`
+          ),
+        ],
+      },
+      createStreamConfig(`${nonce}-thread`)
+    );
+
+    const agentIds = new Set(
+      capture.contextEvents.map((event) => event.agentId)
+    );
+    expect(agentIds.has('router')).toBe(true);
+    expect(agentIds.has('specialist')).toBe(true);
+
+    for (const event of capture.contextEvents) {
+      expect(event.breakdown.maxContextTokens).toBe(MAX_CONTEXT_TOKENS);
+      expect(event.contextBudget).toBeLessThanOrEqual(MAX_CONTEXT_TOKENS);
+      expect(event.remainingContextTokens).toBeGreaterThan(0);
+    }
+
+    /** One snapshot per real model call — no ghost snapshots */
+    expect(capture.collectedUsage.length).toBe(capture.contextEvents.length);
+    expect(capture.collectedUsage.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('keeps subagent runs isolated from parent context/usage events', async () => {
+    const capture = createCapture();
+    const parent = createAnthropicAgent(
+      'parent',
+      'You are a supervisor. Delegate research tasks using the subagent tool.',
+      {
+        subagentConfigs: [
+          {
+            type: 'researcher',
+            name: 'Research Agent',
+            description: 'Researches and summarizes information',
+            agentInputs: createAnthropicAgent(
+              'researcher',
+              'You are a research agent. Answer in one short sentence.'
+            ),
+          },
+        ],
+      }
+    );
+
+    const run = await Run.create<t.IState>({
+      runId: `ctx-live-subagent-${Date.now()}`,
+      graphConfig: { type: 'standard', agents: [parent] },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers: capture.handlers,
+      tokenCounter,
+      indexTokenCountMap: {},
+    });
+
+    /** Parent is a fake forced to call the subagent tool — the child run
+     *  executes on the real provider, exercising real isolation */
+    const subagentToolCall: ToolCall = {
+      id: 'call_subagent_live',
+      name: Constants.SUBAGENT,
+      args: {
+        description: 'What is the capital of France? One short sentence.',
+        subagent_type: 'researcher',
+      },
+      type: 'tool_call',
+    };
+    run.Graph?.overrideTestModel(
+      ['Delegating to the researcher.', 'The researcher confirmed the answer.'],
+      10,
+      [subagentToolCall]
+    );
+
+    await run.processStream(
+      { messages: [new HumanMessage('What is the capital of France?')] },
+      createStreamConfig(`ctx-live-subagent-${Date.now()}`)
+    );
+
+    /** Child progress arrives only as wrapped subagent updates */
+    expect(capture.subagentUpdates.length).toBeGreaterThan(0);
+
+    /** No raw child snapshots leak into the parent handler registry */
+    const childContextEvents = capture.contextEvents.filter(
+      (event) => event.agentId !== 'parent'
+    );
+    expect(childContextEvents).toHaveLength(0);
+    for (const event of capture.contextEvents) {
+      expect(event.agentId).toBe('parent');
+    }
+
+    /** Documented isolation: child model-call usage does not reach the
+     *  parent's collected usage (fake parent emits no usage_metadata) */
+    expect(capture.collectedUsage).toHaveLength(0);
+
+    const toolMessage = (run.getRunMessages() ?? []).find(
+      (message) =>
+        message.getType() === 'tool' &&
+        (message as { name?: string }).name === Constants.SUBAGENT
+    );
+    expect(toolMessage).toBeDefined();
+    expect(String(toolMessage?.content ?? '').toLowerCase()).toContain('paris');
+  });
+});

package/src/specs/prune.test.ts

@@ -472,6 +472,53 @@ describe('Prune Messages Tests', () => {
       expect(typeof result.remainingContextTokens).toBe('number');
     });
 
+    it('should return remaining tokens in calibrated units when pruning with calibration', () => {
+      const tokenCounter = createTestTokenCounter();
+      const messages = [
+        new SystemMessage('System instruction'),
+        new HumanMessage('Message 1'),
+        new AIMessage('Response 1'),
+        new HumanMessage('Message 2'),
+        new AIMessage('Response 2'),
+      ];
+
+      const indexTokenCountMap = {
+        0: tokenCounter(messages[0]),
+        1: tokenCounter(messages[1]),
+        2: tokenCounter(messages[2]),
+        3: tokenCounter(messages[3]),
+        4: tokenCounter(messages[4]),
+      };
+
+      const calibrationRatio = 2;
+      const maxTokens = 80;
+      const pruneMessages = createPruneMessages({
+        maxTokens,
+        startIndex: 0,
+        tokenCounter,
+        indexTokenCountMap,
+        reserveRatio: 0,
+        calibrationRatio,
+      });
+
+      const result = pruneMessages({ messages });
+
+      expect(result.messagesToRefine?.length).toBeGreaterThan(0);
+
+      /** Pruning selects within rawSpaceBudget = maxTokens / ratio (raw units,
+       *  minus the 3-token assistant label); the returned remaining must be
+       *  scaled back so `budget - remaining` reflects provider-space usage */
+      const keptRaw = result.context.reduce(
+        (sum, msg) => sum + tokenCounter(msg),
+        0
+      );
+      const rawSpaceBudget = Math.round(maxTokens / calibrationRatio);
+      const expectedRemaining =
+        (rawSpaceBudget - keptRaw - 3) * calibrationRatio;
+      expect(result.remainingContextTokens).toBe(expectedRemaining);
+      expect(result.contextBudget).toBe(maxTokens);
+    });
+
     it('should respect startType parameter', () => {
       const tokenCounter = createTestTokenCounter();
       const messages = [
@@ -1397,7 +1444,10 @@ describe('Prune Messages Tests', () => {
       expect(result.context).toEqual([]);
       expect(result.messagesToRefine).toEqual([]);
       expect(result.prePruneContextTokens).toBe(0);
-      expect(result.remainingContextTokens).toBe(8000);
+      /** Reserve-adjusted budget (8000 − 5%) minus instruction overhead */
+      expect(result.contextBudget).toBe(7600);
+      expect(result.effectiveInstructionTokens).toBe(4000);
+      expect(result.remainingContextTokens).toBe(3600);
     });
   });
 

package/src/specs/subagent.test.ts

@@ -1,6 +1,12 @@
+import { ChatGenerationChunk } from '@langchain/core/outputs';
 import { FakeListChatModel } from '@langchain/core/utils/testing';
-import { AIMessage, HumanMessage } from '@langchain/core/messages';
+import {
+  AIMessage,
+  AIMessageChunk,
+  HumanMessage,
+} from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
+import type { UsageMetadata } from '@langchain/core/messages';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type * as t from '@/types';
 import {
@@ -388,4 +394,121 @@ describe('Subagent Integration', () => {
       contextWithout!.toolSchemaTokens
     );
   });
+
+  it('reports child model usage through subagentUsageSink', async () => {
+    const CHILD_USAGE = {
+      input_tokens: 11,
+      output_tokens: 7,
+      total_tokens: 18,
+    };
+    /**
+     * The default mock (FakeListChatModel) reports no usage. Re-mock with a
+     * subclass that reports `usage_metadata` the way live providers do:
+     * stamped on the generation in the invoke path, and carried on a final
+     * zero-content chunk in the stream path (the graph's `attemptInvoke`
+     * prefers `model.stream()`, and chunk concatenation folds the usage
+     * into the aggregated message that `handleLLMEnd` receives).
+     */
+    getChatModelClassSpy.mockImplementation(((provider: Providers) => {
+      if (provider === Providers.OPENAI) {
+        return class extends FakeListChatModel {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          constructor(_options: any) {
+            super({ responses: [CHILD_RESPONSE] });
+          }
+          async _generate(
+            ...args: Parameters<FakeListChatModel['_generate']>
+          ): ReturnType<FakeListChatModel['_generate']> {
+            const result = await super._generate(...args);
+            for (const generation of result.generations) {
+              (generation.message as AIMessage).usage_metadata = {
+                ...CHILD_USAGE,
+              };
+            }
+            return result;
+          }
+          async *_streamResponseChunks(
+            ...args: Parameters<FakeListChatModel['_streamResponseChunks']>
+          ): ReturnType<FakeListChatModel['_streamResponseChunks']> {
+            yield* super._streamResponseChunks(...args);
+            yield new ChatGenerationChunk({
+              text: '',
+              message: new AIMessageChunk({
+                content: '',
+                usage_metadata: { ...CHILD_USAGE },
+              }),
+            });
+          }
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        } as any;
+      }
+      return originalGetChatModelClass(provider);
+    }) as typeof providers.getChatModelClass);
+
+    const collectedUsage: UsageMetadata[] = [];
+    const sunkEvents: t.SubagentUsageEvent[] = [];
+    const customHandlers: Record<string, t.EventHandler> = {
+      [GraphEvents.TOOL_END]: new ToolEndHandler(),
+      [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(collectedUsage),
+    };
+
+    const runId = `subagent-usage-${Date.now()}`;
+    const run = await Run.create<t.IState>({
+      runId,
+      graphConfig: {
+        type: 'standard',
+        agents: [createParentAgent()],
+      },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers,
+      subagentUsageSink: (event) => {
+        sunkEvents.push(event);
+      },
+    });
+
+    const subagentToolCall: ToolCall = {
+      id: 'call_subagent_usage',
+      name: Constants.SUBAGENT,
+      args: {
+        description: 'What is the capital of France?',
+        subagent_type: 'researcher',
+      },
+      type: 'tool_call',
+    };
+
+    run.Graph?.overrideTestModel(
+      [
+        'Let me delegate this research task.',
+        `Based on the research: ${CHILD_RESPONSE}`,
+      ],
+      10,
+      [subagentToolCall]
+    );
+
+    await run.processStream(
+      { messages: [new HumanMessage('What is the capital of France?')] },
+      callerConfig
+    );
+
+    /** Child made exactly one model call; all events are child-tagged. */
+    expect(sunkEvents).toHaveLength(1);
+    const event = sunkEvents[0];
+    /** Chunk concat adds empty `*_token_details` — match on the counts. */
+    expect(event.usage).toMatchObject(CHILD_USAGE);
+    expect(event.subagentType).toBe('researcher');
+    expect(event.subagentAgentId).toBe('researcher');
+    expect(event.provider).toBe(Providers.OPENAI);
+    /** FakeListChatModel emits no ls_model_name → config fallback. */
+    expect(event.model).toBe('gpt-4o-mini');
+    expect(event.runId).toBe(runId);
+    expect(event.subagentRunId).toContain(`${runId}_sub_`);
+    /**
+     * The parent's own calls must NOT be routed through the sink — they
+     * flow through the registered CHAT_MODEL_END handler. (The fake
+     * override model reports no usage, so collectedUsage stays empty;
+     * the load-bearing assertion is that the sink saw no parent calls.)
+     */
+    expect(sunkEvents.every((e) => e.subagentType === 'researcher')).toBe(true);
+  });
 });

package/src/summarization/__tests__/node.test.ts

@@ -6,8 +6,8 @@ import {
   DEFAULT_SUMMARIZATION_PROMPT,
   DEFAULT_UPDATE_SUMMARIZATION_PROMPT,
 } from '@/summarization/node';
+import { Constants, GraphEvents, Providers } from '@/common';
 import { AgentContext } from '@/agents/AgentContext';
-import { GraphEvents, Providers } from '@/common';
 import * as providers from '@/llm/providers';
 import * as eventUtils from '@/utils/events';
 
@@ -216,6 +216,65 @@ describe('createSummarizeNode', () => {
     ).toBeUndefined();
   });
 
+  it('stamps INVOKED_MODEL/INVOKED_PROVIDER metadata for a dedicated summarizer model', async () => {
+    captureEvents();
+
+    const capturedConfigs: unknown[] = [];
+    jest.spyOn(providers, 'getChatModelClass').mockReturnValue(
+      class {
+        constructor() {
+          return {
+            invoke: jest
+              .fn()
+              .mockImplementation(
+                async (_messages: unknown, config?: unknown) => {
+                  capturedConfigs.push(config);
+                  return { content: 'Summary text' };
+                }
+              ),
+          };
+        }
+      } as never
+    );
+
+    const agentContext = createAgentContext({
+      summarizationConfig: {
+        retainRecent: { turns: 0 },
+        model: 'gpt-4.1-mini',
+      },
+    });
+    const graph = mockGraph();
+    const node = createSummarizeNode({
+      agentContext,
+      graph,
+      generateStepId,
+    });
+
+    await node(
+      {
+        messages: [new HumanMessage('Hello'), new HumanMessage('World')],
+        summarizationRequest: {
+          remainingContextTokens: 1000,
+          agentId: 'agent_0',
+        },
+      },
+      {} as RunnableConfig
+    );
+
+    /**
+     * Usage consumers (the subagent usage-capture handler) attribute the
+     * call from these keys — without them, a summarizer model that differs
+     * from the agent's primary would be billed against the primary config.
+     */
+    const config = capturedConfigs[0] as {
+      metadata?: Record<string, unknown>;
+    };
+    expect(config.metadata?.[Constants.INVOKED_MODEL]).toBe('gpt-4.1-mini');
+    expect(config.metadata?.[Constants.INVOKED_PROVIDER]).toBe(
+      Providers.OPENAI
+    );
+  });
+
   it('collects streamed text when model supports stream()', async () => {
     captureEvents();
 

package/src/summarization/node.ts

@@ -10,7 +10,13 @@ import type { AgentContext } from '@/agents/AgentContext';
 import type { HookRegistry } from '@/hooks';
 import type { OnChunk } from '@/llm/invoke';
 import type * as t from '@/types';
-import { ContentTypes, GraphEvents, StepTypes, Providers } from '@/common';
+import {
+  Constants,
+  ContentTypes,
+  GraphEvents,
+  StepTypes,
+  Providers,
+} from '@/common';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
 import { attemptInvoke, tryFallbackProviders } from '@/llm/invoke';
 import { createRemoveAllMessage } from '@/messages/reducer';
@@ -938,6 +944,19 @@ export function createSummarizeNode({
           agent_id: request.agentId,
           summarization_provider: clientConfig.provider,
           summarization_model: clientConfig.modelName,
+          /**
+             * Per-call model attribution for usage consumers (the subagent
+             * usage-capture handler): the summarizer's model can differ from
+             * the agent's primary, and providers that emit no `ls_model_name`
+             * would otherwise be billed against the primary config's model.
+             * Omitted for self-summarize (no explicit model — the primary
+             * config fallback is then correct). `tryFallbackProviders`
+             * overrides this per fallback attempt; `INVOKED_PROVIDER` is
+             * stamped by `attemptInvoke` itself.
+             */
+          ...(clientConfig.modelName != null && clientConfig.modelName !== ''
+            ? { [Constants.INVOKED_MODEL]: clientConfig.modelName }
+            : {}),
         },
       }
       : undefined;