@librechat/agents 3.3.3 → 3.3.4

package/src/llm/openrouter/reasoning.test.ts

@@ -1,5 +1,10 @@
+import { tools as openAITools } from '@langchain/openai';
+import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
 import type { OpenAIChatInput } from '@langchain/openai';
 import type { OpenRouterReasoning, ChatOpenRouterCallOptions } from './index';
+import type { GraphTools } from '@/types';
+import { partitionAndMarkOpenRouterToolCache } from './toolCache';
+import { addTailCacheControl } from '@/messages/cache';
 import { ChatOpenRouter } from './index';
 
 type CreateRouterOptions = Partial<
@@ -245,3 +250,312 @@ describe('ChatOpenRouter reasoning handling', () => {
     });
   });
 });
+
+describe('ChatOpenRouter Responses prompt caching', () => {
+  it('maps promptCache to the Responses top-level cache control', () => {
+    const router = new ChatOpenRouter({
+      model: 'anthropic/claude-sonnet-4',
+      apiKey: 'test-key',
+      useResponsesApi: true,
+      promptCache: true,
+      promptCacheTtl: '1h',
+    });
+
+    expect(router.invocationParams().cache_control).toEqual({
+      type: 'ephemeral',
+      ttl: '1h',
+    });
+  });
+
+  it('sends cache control on the actual Responses request', async () => {
+    const router = new ChatOpenRouter({
+      model: 'openai/gpt-4.1',
+      apiKey: 'test-key',
+      useResponsesApi: true,
+      promptCache: true,
+      promptCacheTtl: '1h',
+      streaming: false,
+    });
+    const sentinel = new Error('captured request');
+    let capturedRequest: unknown;
+    const responses = (
+      router as unknown as {
+        responses: {
+          completionWithRetry: (request: unknown) => Promise<never>;
+        };
+      }
+    ).responses;
+    responses.completionWithRetry = async (request) => {
+      capturedRequest = request;
+      throw sentinel;
+    };
+
+    await expect(router.invoke([new HumanMessage('hello')])).rejects.toThrow(
+      sentinel
+    );
+    expect(capturedRequest).toMatchObject({
+      cache_control: { type: 'ephemeral', ttl: '1h' },
+      input: [{ type: 'message', role: 'user', content: 'hello' }],
+    });
+  });
+
+  it('honors per-call Responses cache overrides', async () => {
+    const router = new ChatOpenRouter({
+      model: 'openai/gpt-4.1',
+      apiKey: 'test-key',
+      useResponsesApi: true,
+      promptCache: false,
+      streaming: false,
+    });
+    const sentinel = new Error('captured override');
+    let capturedRequest: unknown;
+    const responses = (
+      router as unknown as {
+        responses: {
+          completionWithRetry: (request: unknown) => Promise<never>;
+        };
+      }
+    ).responses;
+    responses.completionWithRetry = async (request) => {
+      capturedRequest = request;
+      throw sentinel;
+    };
+
+    await expect(
+      router.invoke([new HumanMessage('hello')], {
+        promptCache: true,
+        promptCacheTtl: '5m',
+      } as unknown as Parameters<typeof router.invoke>[1])
+    ).rejects.toThrow(sentinel);
+    expect(capturedRequest).toMatchObject({
+      cache_control: { type: 'ephemeral' },
+    });
+    expect(JSON.stringify(capturedRequest)).not.toContain('"ttl"');
+  });
+
+  it('removes tail block markers added after invocation normalization', async () => {
+    const router = new ChatOpenRouter({
+      model: 'openai/gpt-4.1',
+      apiKey: 'test-key',
+      useResponsesApi: true,
+      promptCache: true,
+      streaming: false,
+    });
+    const sentinel = new Error('captured tail cache');
+    let capturedRequest: unknown;
+    const responses = (
+      router as unknown as {
+        responses: {
+          completionWithRetry: (request: unknown) => Promise<never>;
+        };
+      }
+    ).responses;
+    responses.completionWithRetry = async (request) => {
+      capturedRequest = request;
+      throw sentinel;
+    };
+    const messages = addTailCacheControl([
+      new HumanMessage('search'),
+      new AIMessage({
+        content: '',
+        tool_calls: [
+          {
+            id: 'call_cached_result',
+            name: 'search',
+            args: {},
+            type: 'tool_call',
+          },
+        ],
+      }),
+      new ToolMessage({
+        content: 'result body',
+        tool_call_id: 'call_cached_result',
+        name: 'search',
+      }),
+    ]);
+
+    await expect(router.invoke(messages)).rejects.toThrow(sentinel);
+
+    const request = capturedRequest as {
+      cache_control?: unknown;
+      input?: Array<{ type?: string; output?: unknown }>;
+    };
+    expect(
+      request.input?.find((item) => item.type === 'function_call_output')
+    ).toMatchObject({ output: 'result body' });
+    expect(request.cache_control).toEqual({
+      type: 'ephemeral',
+      ttl: '1h',
+    });
+    expect(JSON.stringify(request.input)).not.toContain('cache_control');
+  });
+
+  it('normalizes cache markers for native Responses event streaming', async () => {
+    const router = new ChatOpenRouter({
+      model: 'openai/gpt-4.1',
+      apiKey: 'test-key',
+      useResponsesApi: true,
+      promptCache: true,
+      streaming: true,
+    });
+    let capturedRequest: unknown;
+    const responses = (
+      router as unknown as {
+        responses: {
+          completionWithRetry: (
+            request: unknown
+          ) => Promise<AsyncIterable<never>>;
+          _streamChatModelEvents: (
+            messages: unknown[],
+            options: Record<string, unknown>
+          ) => AsyncIterable<unknown>;
+        };
+      }
+    ).responses;
+    responses.completionWithRetry = async (request) => {
+      capturedRequest = request;
+      return {
+        async *[Symbol.asyncIterator]() {
+          yield* [];
+        },
+      };
+    };
+    const messages = addTailCacheControl([
+      new AIMessage({
+        content: '',
+        tool_calls: [
+          {
+            id: 'call_stream_cache',
+            name: 'search',
+            args: {},
+            type: 'tool_call',
+          },
+        ],
+      }),
+      new ToolMessage({
+        content: 'stream result',
+        tool_call_id: 'call_stream_cache',
+        name: 'search',
+      }),
+    ]);
+
+    for await (const _event of responses._streamChatModelEvents(messages, {})) {
+      // The stubbed provider stream is empty; consuming it triggers request creation.
+    }
+
+    const request = capturedRequest as {
+      input?: Array<{ type?: string; output?: unknown }>;
+      cache_control?: unknown;
+    };
+    expect(
+      request.input?.find((item) => item.type === 'function_call_output')
+    ).toMatchObject({ output: 'stream result' });
+    expect(request.cache_control).toEqual({
+      type: 'ephemeral',
+      ttl: '1h',
+    });
+    expect(JSON.stringify(request.input)).not.toContain('cache_control');
+  });
+
+  it('removes Chat-style tool cache markers from Responses tools', async () => {
+    const router = new ChatOpenRouter({
+      model: 'openai/gpt-4.1',
+      apiKey: 'test-key',
+      useResponsesApi: true,
+      promptCache: true,
+      streaming: false,
+    });
+    const sentinel = new Error('captured tool cache');
+    let capturedRequest: unknown;
+    const responses = (
+      router as unknown as {
+        responses: {
+          completionWithRetry: (request: unknown) => Promise<never>;
+        };
+      }
+    ).responses;
+    responses.completionWithRetry = async (request) => {
+      capturedRequest = request;
+      throw sentinel;
+    };
+    const markedTools = partitionAndMarkOpenRouterToolCache(
+      [
+        {
+          type: 'function',
+          function: {
+            name: 'search',
+            description: 'Search records',
+            parameters: { type: 'object', properties: {} },
+          },
+        },
+      ] as GraphTools,
+      () => false,
+      '1h'
+    )!;
+    const bound = router.bindTools(markedTools);
+
+    await expect(bound.invoke([new HumanMessage('search')])).rejects.toThrow(
+      sentinel
+    );
+
+    const request = capturedRequest as {
+      cache_control?: unknown;
+      tools?: unknown[];
+    };
+    expect(request.cache_control).toEqual({
+      type: 'ephemeral',
+      ttl: '1h',
+    });
+    expect(JSON.stringify(request.tools)).not.toContain('cache_control');
+  });
+
+  it('keeps top-level cache control when a computer tool auto-selects Responses', async () => {
+    const router = new ChatOpenRouter({
+      model: 'openai/gpt-4.1',
+      apiKey: 'test-key',
+      useResponsesApi: false,
+      promptCache: true,
+      streaming: false,
+    });
+    const sentinel = new Error('captured computer cache');
+    let capturedRequest: unknown;
+    const responses = (
+      router as unknown as {
+        responses: {
+          completionWithRetry: (request: unknown) => Promise<never>;
+        };
+      }
+    ).responses;
+    responses.completionWithRetry = async (request) => {
+      capturedRequest = request;
+      throw sentinel;
+    };
+    const bound = router.bindTools([
+      openAITools.computerUse({
+        displayWidth: 1024,
+        displayHeight: 768,
+        environment: 'browser',
+        execute: async () => 'data:image/png;base64,AA==',
+      }),
+    ]);
+
+    await expect(bound.invoke([new HumanMessage('inspect')])).rejects.toThrow(
+      sentinel
+    );
+
+    expect(capturedRequest).toMatchObject({
+      cache_control: { type: 'ephemeral', ttl: '1h' },
+    });
+  });
+
+  it('keeps Chat prompt caching on content blocks', () => {
+    const router = new ChatOpenRouter({
+      model: 'anthropic/claude-sonnet-4',
+      apiKey: 'test-key',
+      useResponsesApi: false,
+      promptCache: true,
+    });
+
+    expect(router.invocationParams().cache_control).toBeUndefined();
+  });
+});

package/src/messages/__tests__/observationMasking.test.ts

@@ -1,12 +1,15 @@
 import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { TokenCounter } from '@/types/run';
-import { maskConsumedToolResults } from '@/messages/prune';
+import {
+  maskConsumedToolResults,
+  ORIGINAL_CONTENT_MAX_CHARS,
+} from '@/messages/prune';
 
 const charCounter: TokenCounter = (msg) => {
   const raw = msg.content;
   if (typeof raw === 'string') return raw.length;
-  return 0;
+  return JSON.stringify(raw).length;
 };
 
 function toolMsg(
@@ -209,6 +212,94 @@ describe('maskConsumedToolResults', () => {
     expect(map[2]).toBe((messages[2].content as string).length);
   });
 
+  it('masks consumed structured tool results with a bounded text preview', () => {
+    const tcId = 'tc-structured';
+    const toolMessage = new ToolMessage({
+      content: [
+        {
+          type: 'json',
+          rows: Array.from({ length: 20 }, (_, index) => ({
+            id: index,
+            value: `${'x'.repeat(100)}-${index}`,
+          })),
+        },
+      ],
+      tool_call_id: tcId,
+      name: 'run_select_query',
+      status: 'success',
+      artifact: { source: 'clickhouse' },
+    });
+    const messages: BaseMessage[] = [
+      new HumanMessage('query the table'),
+      aiToolCall(tcId, 'run_select_query'),
+      toolMessage,
+      aiWithText('The query returned 20 rows.'),
+    ];
+    const map: Record<string, number | undefined> = {
+      0: 5,
+      1: 20,
+      2: 0,
+      3: 30,
+    };
+    const originalContentStore = new Map<number, string>();
+    const originalContent = JSON.stringify(toolMessage.content);
+
+    const count = maskConsumedToolResults({
+      messages,
+      indexTokenCountMap: map,
+      tokenCounter: charCounter,
+      originalContentStore,
+    });
+
+    expect(count).toBe(1);
+    expect(typeof messages[2].content).toBe('string');
+    expect(messages[2].content).toContain('truncated');
+    expect((messages[2].content as string).length).toBeLessThanOrEqual(300);
+    const masked = messages[2] as ToolMessage;
+    expect(masked.tool_call_id).toBe(tcId);
+    expect(masked.name).toBe('run_select_query');
+    expect(masked.status).toBe('success');
+    expect(masked.artifact).toEqual({ source: 'clickhouse' });
+    expect(map[2]).toBe(charCounter(masked));
+    expect(originalContentStore.get(2)).toBe(originalContent);
+  });
+
+  it('bounds stored structured originals without invoking custom toJSON', () => {
+    const tcId = 'tc-large-structured';
+    const toJSON = jest.fn(() => ({ expanded: 'should not run' }));
+    const messages: BaseMessage[] = [
+      new HumanMessage('query the table'),
+      aiToolCall(tcId, 'run_select_query'),
+      new ToolMessage({
+        content: [
+          {
+            type: 'json',
+            payload: 'x'.repeat(ORIGINAL_CONTENT_MAX_CHARS + 1_000),
+            toJSON,
+          },
+        ],
+        tool_call_id: tcId,
+        name: 'run_select_query',
+      }),
+      aiWithText('The query completed.'),
+    ];
+    const originalContentStore = new Map<number, string>();
+
+    const count = maskConsumedToolResults({
+      messages,
+      indexTokenCountMap: { 0: 1, 1: 1, 2: 1, 3: 1 },
+      tokenCounter: () => 1,
+      originalContentStore,
+    });
+
+    expect(count).toBe(1);
+    expect(toJSON).not.toHaveBeenCalled();
+    expect(originalContentStore.get(2)?.length).toBeLessThanOrEqual(
+      ORIGINAL_CONTENT_MAX_CHARS
+    );
+    expect(originalContentStore.get(2)).toContain('truncated');
+  });
+
   it('handles empty messages array', () => {
     const map: Record<string, number | undefined> = {};
     const count = maskConsumedToolResults({

package/src/messages/cache.tail.test.ts

@@ -1,3 +1,4 @@
+import { convertMessagesToCompletionsMessageParams } from '@langchain/openai';
 import {
   AIMessage,
   HumanMessage,
@@ -10,7 +11,15 @@ import type {
 } from '@langchain/core/messages';
 import type Anthropic from '@anthropic-ai/sdk';
 import type { AnthropicMessages } from '@/types/messages';
+import {
+  projectOpenAIChatToolMessageContent,
+  projectOpenAIToolMessageContent,
+  projectOpenAIResponsesToolMessageContent,
+  projectOpenRouterToolMessageContent,
+  projectComputerCallOutputsToText,
+} from './core';
 import { addTailCacheControl, addBedrockTailCacheControl } from './cache';
+import { convertToConverseMessages } from '@/llm/bedrock/utils';
 import { toLangChainContent } from './langchain';
 
 type CacheControlBlock = MessageContentComplex & {
@@ -86,6 +95,154 @@ describe('addTailCacheControl (single tail breakpoint)', () => {
     expect(blocksOf(result[2])[0].cache_control).toEqual({ type: 'ephemeral' });
   });
 
+  test('skips native computer outputs and removes stale screenshot markers', () => {
+    const computerCall = new AIMessage({
+      content: '',
+      response_metadata: {
+        output: [
+          {
+            type: 'computer_call',
+            call_id: 'call_computer_cache',
+            action: { type: 'screenshot' },
+          },
+        ],
+      },
+    });
+    const computerOutput = new ToolMessage({
+      content: 'data:image/png;base64,AA==',
+      tool_call_id: 'call_computer_cache',
+      additional_kwargs: { type: 'computer_call_output' },
+    });
+    const canonical = projectOpenAIToolMessageContent([
+      new HumanMessage('Take a screenshot'),
+      computerCall,
+      computerOutput,
+    ]);
+
+    const cached = addTailCacheControl(canonical);
+
+    expect(countCacheMarkers(cached)).toBe(1);
+    expect(blocksOf(cached[0])[0].cache_control).toEqual({
+      type: 'ephemeral',
+    });
+    expect(blocksOf(cached[2])[0]).not.toHaveProperty('cache_control');
+    expect(() =>
+      projectOpenAIResponsesToolMessageContent(cached)
+    ).not.toThrow();
+
+    const canonicalOutput = canonical[2] as ToolMessage;
+    const staleOutput = new ToolMessage({
+      content: toLangChainContent([
+        {
+          ...(canonicalOutput.content[0] as MessageContentComplex),
+          cache_control: { type: 'ephemeral' },
+        },
+      ]),
+      tool_call_id: canonicalOutput.tool_call_id,
+      additional_kwargs: canonicalOutput.additional_kwargs,
+    });
+    const cleaned = addTailCacheControl([
+      canonical[0],
+      canonical[1],
+      staleOutput,
+    ]);
+
+    expect(countCacheMarkers(cleaned)).toBe(1);
+    expect(blocksOf(cleaned[2])[0]).not.toHaveProperty('cache_control');
+    expect(blocksOf(staleOutput)[0]).toHaveProperty('cache_control');
+    expect(() =>
+      projectOpenAIResponsesToolMessageContent(cleaned)
+    ).not.toThrow();
+  });
+
+  test('keeps a cached tool result structured through Chat projection', () => {
+    const toolCall = new AIMessage({
+      content: '',
+      tool_calls: [{ id: 'call_cached_tool', name: 'search', args: {} }],
+    });
+    const toolOutput = new ToolMessage({
+      content: 'result body',
+      tool_call_id: 'call_cached_tool',
+    });
+    const graphProjected = projectOpenAIToolMessageContent([
+      new HumanMessage('Search'),
+      toolCall,
+      toolOutput,
+    ]);
+    const cached = addTailCacheControl(graphProjected);
+    const attemptProjected = projectOpenRouterToolMessageContent(cached);
+    const payload = convertMessagesToCompletionsMessageParams({
+      messages: attemptProjected,
+      model: 'gpt-4o',
+    });
+
+    expect(blocksOf(cached[2])[0]).toMatchObject({
+      type: 'text',
+      text: 'result body',
+      cache_control: { type: 'ephemeral' },
+    });
+    expect((attemptProjected[2] as ToolMessage).content).toEqual(
+      (cached[2] as ToolMessage).content
+    );
+    expect(payload[2]).toMatchObject({
+      role: 'tool',
+      tool_call_id: 'call_cached_tool',
+      content: [
+        {
+          type: 'text',
+          text: 'result body',
+          cache_control: { type: 'ephemeral' },
+        },
+      ],
+    });
+
+    const fallbackProjected = projectOpenAIChatToolMessageContent(cached);
+    const fallbackPayload = convertMessagesToCompletionsMessageParams({
+      messages: fallbackProjected,
+      model: 'gpt-4o',
+    });
+
+    expect((fallbackProjected[2] as ToolMessage).content).toBe('result body');
+    expect(fallbackPayload[2]).toMatchObject({
+      role: 'tool',
+      tool_call_id: 'call_cached_tool',
+      content: 'result body',
+    });
+    expect(JSON.stringify(fallbackPayload[2])).not.toContain('cache_control');
+
+    expect(
+      typeof (projectOpenAIToolMessageContent(cached)[2] as ToolMessage).content
+    ).toBe('string');
+  });
+
+  test('does not stringify noncanonical cache metadata into tool output', () => {
+    const messages = addTailCacheControl<BaseMessage>([
+      new HumanMessage('Search'),
+      new AIMessage({
+        content: '',
+        tool_calls: [{ id: 'call_nested_cache', name: 'search', args: {} }],
+      }),
+      new ToolMessage({
+        content: toLangChainContent([
+          {
+            type: 'tool_result',
+            tool_use_id: 'call_nested_cache',
+            content: 'result body',
+          },
+        ] as MessageContentComplex[]),
+        tool_call_id: 'call_nested_cache',
+      }),
+    ]);
+
+    const projected = projectOpenRouterToolMessageContent(messages);
+    const content = (projected[2] as ToolMessage).content;
+
+    expect(typeof content).toBe('string');
+    expect(content).toContain('result body');
+    expect(content).not.toContain('cache_control');
+    expect(JSON.stringify(messages[2].content)).toContain('cache_control');
+  });
+
   test('strips ALL stale markers and re-anchors a single one at the tail', () => {
     const messages: BaseMessage[] = [
       new HumanMessage({
@@ -337,4 +494,40 @@ describe('addBedrockTailCacheControl (single tail cachePoint)', () => {
       { cachePoint: { type: 'default' } },
     ]);
   });
+
+  test('keeps the cachePoint before an omitted computer screenshot', () => {
+    const computerOutput = new ToolMessage({
+      content: 'data:image/png;base64,AA==',
+      tool_call_id: 'call_bedrock_computer',
+      additional_kwargs: { type: 'computer_call_output' },
+    });
+    const cached = addBedrockTailCacheControl([
+      new HumanMessage('Take a screenshot'),
+      new AIMessage({
+        content: '',
+        tool_calls: [
+          {
+            id: 'call_bedrock_computer',
+            name: 'computer',
+            args: { action: 'screenshot' },
+          },
+        ],
+      }),
+      computerOutput,
+    ]);
+
+    expect(countCachePoints(cached)).toBe(1);
+    expect(blocksOf(cached[0])[1]).toEqual({
+      cachePoint: { type: 'default' },
+    });
+    expect(cached[2].content).toBe(computerOutput.content);
+
+    const projected = projectComputerCallOutputsToText(cached);
+    const converse = convertToConverseMessages(projected);
+    expect((projected[2] as ToolMessage).content).toBe(
+      '[Computer screenshot omitted for this provider]'
+    );
+    expect(JSON.stringify(converse).match(/"cachePoint"/g)).toHaveLength(1);
+    expect(computerOutput.content).toBe('data:image/png;base64,AA==');
+  });
 });