@librechat/agents 3.3.3 → 3.3.5

package/src/llm/openai/utils/messages.test.ts

@@ -1,5 +1,10 @@
 import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
-import { _convertMessagesToOpenAIParams } from './index';
+import {
+  _convertMessagesToOpenAIParams,
+  _convertMessagesToOpenAIResponsesParams,
+} from './index';
+import { calculateMaxToolCallInputChars } from '@/messages/prune';
+import { HARD_MAX_TOOL_RESULT_CHARS } from '@/utils/truncation';
 
 describe('_convertMessagesToOpenAIParams', () => {
   it('includes reasoning_content for assistant messages in tool-call context when requested', () => {
@@ -156,4 +161,328 @@ describe('_convertMessagesToOpenAIParams', () => {
       })
     );
   });
+
+  it('bounds structured function-tool output for Chat and Responses adapters', () => {
+    let toJSONCalls = 0;
+    const toolMessage = new ToolMessage({
+      content: [
+        { type: 'text', text: 'rendered chart' },
+        {
+          type: 'image_url',
+          image_url: {
+            url: `data:image/png;base64,${'A'.repeat(
+              HARD_MAX_TOOL_RESULT_CHARS + 1_000
+            )}`,
+          },
+          toJSON() {
+            toJSONCalls++;
+            return { expanded: 'B'.repeat(HARD_MAX_TOOL_RESULT_CHARS * 2) };
+          },
+        },
+      ],
+      tool_call_id: 'call_structured',
+    });
+
+    const chat = _convertMessagesToOpenAIParams([toolMessage]);
+    const responses = _convertMessagesToOpenAIResponsesParams([toolMessage]);
+    const chatContent = chat[0].content;
+
+    expect(typeof chatContent).toBe('string');
+    expect((chatContent as string).length).toBeLessThanOrEqual(
+      HARD_MAX_TOOL_RESULT_CHARS
+    );
+    expect(responses[0]).toMatchObject({
+      type: 'function_call_output',
+      call_id: 'call_structured',
+      output: chatContent,
+    });
+    expect(toJSONCalls).toBe(0);
+    expect(Array.isArray(toolMessage.content)).toBe(true);
+  });
+
+  it('preserves canonical OpenRouter cache blocks only when requested', () => {
+    const toolMessage = new ToolMessage({
+      content: [
+        {
+          type: 'text',
+          text: 'result body',
+          cache_control: { type: 'ephemeral', ttl: '1h' },
+        },
+      ],
+      tool_call_id: 'call_cached',
+    });
+
+    const defaultContent = _convertMessagesToOpenAIParams([toolMessage])[0]
+      .content;
+    const openRouterContent = _convertMessagesToOpenAIParams(
+      [toolMessage],
+      'anthropic/claude-sonnet-4',
+      { preserveToolCacheControl: true }
+    )[0].content;
+
+    expect(typeof defaultContent).toBe('string');
+    expect(openRouterContent).toEqual(toolMessage.content);
+  });
+
+  it('bounds direct structured tool-call args without invoking accessors or toJSON', () => {
+    const maxInputChars = calculateMaxToolCallInputChars();
+    let getterCalls = 0;
+    let toJSONCalls = 0;
+    const args: Record<string, unknown> = {
+      query: 'safe',
+      payload: 'x'.repeat(maxInputChars + 1_000),
+    };
+    Object.defineProperty(args, 'expanded', {
+      enumerable: true,
+      get() {
+        getterCalls++;
+        return 'y'.repeat(maxInputChars * 2);
+      },
+    });
+    args.self = args;
+    args.toJSON = (): Record<string, string> => {
+      toJSONCalls++;
+      return { payload: 'z'.repeat(maxInputChars * 2) };
+    };
+    const message = new AIMessage({
+      content: '',
+      tool_calls: [
+        {
+          id: 'call_adversarial',
+          name: 'lookup',
+          args,
+        },
+      ],
+    });
+
+    const chat = _convertMessagesToOpenAIParams([message]);
+    const responses = _convertMessagesToOpenAIResponsesParams([message]);
+    const chatArguments = (
+      chat[0] as {
+        tool_calls: Array<{ function: { arguments: string } }>;
+      }
+    ).tool_calls[0].function.arguments;
+    const responseArguments = (
+      responses.find((item) => item.type === 'function_call') as {
+        arguments: string;
+      }
+    ).arguments;
+
+    expect(chatArguments).toBe(responseArguments);
+    expect(chatArguments.length).toBeLessThanOrEqual(maxInputChars);
+    expect(() => JSON.parse(chatArguments)).not.toThrow();
+    expect(getterCalls).toBe(0);
+    expect(toJSONCalls).toBe(0);
+    expect(args.self).toBe(args);
+  });
+
+  it('bounds and synchronizes raw Chat and Responses function-call arguments', () => {
+    const maxInputChars = calculateMaxToolCallInputChars();
+    const rawArguments = `{"payload":"${'x'.repeat(maxInputChars + 1_000)}"}`;
+    const rawOnlyMessage = new AIMessage({
+      content: '',
+      additional_kwargs: {
+        tool_calls: [
+          {
+            id: 'call_raw',
+            type: 'function',
+            function: { name: 'lookup', arguments: rawArguments },
+          },
+        ],
+      },
+      response_metadata: {
+        output: [
+          {
+            type: 'function_call',
+            id: 'fc_raw',
+            call_id: 'call_raw',
+            name: 'lookup',
+            arguments: rawArguments,
+          },
+        ],
+      },
+    });
+
+    const chat = _convertMessagesToOpenAIParams([rawOnlyMessage]);
+    const responses = _convertMessagesToOpenAIResponsesParams([rawOnlyMessage]);
+    const chatArguments = (
+      chat[0] as {
+        tool_calls: Array<{ function: { arguments: string } }>;
+      }
+    ).tool_calls[0].function.arguments;
+    const responseArguments = (
+      responses.find((item) => item.type === 'function_call') as {
+        arguments: string;
+      }
+    ).arguments;
+
+    expect(chatArguments.length).toBeLessThanOrEqual(maxInputChars);
+    expect(responseArguments.length).toBeLessThanOrEqual(maxInputChars);
+    expect(() => JSON.parse(chatArguments)).not.toThrow();
+    expect(() => JSON.parse(responseArguments)).not.toThrow();
+    expect(
+      (
+        rawOnlyMessage.additional_kwargs.tool_calls as Array<{
+          function: { arguments: string };
+        }>
+      )[0].function.arguments
+    ).toBe(rawArguments);
+    expect(
+      (
+        rawOnlyMessage.response_metadata.output as Array<{
+          arguments: string;
+        }>
+      )[0].arguments
+    ).toBe(rawArguments);
+  });
+
+  it('normalizes legacy function calls before wire serialization', () => {
+    let toJSONCalls = 0;
+    const functionCall = {
+      name: 'legacy_lookup',
+      arguments: '{}',
+    };
+    const message = new AIMessage({
+      content: '',
+      additional_kwargs: {
+        function_call: functionCall,
+      },
+    });
+    Object.defineProperty(functionCall, 'toJSON', {
+      enumerable: true,
+      value: () => {
+        toJSONCalls++;
+        return {
+          name: 'legacy_lookup',
+          arguments: 'x'.repeat(500_000),
+        };
+      },
+    });
+
+    const [chat] = _convertMessagesToOpenAIParams([message]);
+    const serialized = JSON.stringify(chat);
+
+    expect(chat).toMatchObject({
+      role: 'assistant',
+      function_call: {
+        name: 'legacy_lookup',
+        arguments: '{}',
+      },
+    });
+    expect(serialized.length).toBeLessThanOrEqual(300);
+    expect(toJSONCalls).toBe(0);
+  });
+
+  it('makes Responses raw reuse match the projected LangChain tool-call args', () => {
+    const message = new AIMessage({
+      content: '',
+      tool_calls: [
+        {
+          id: 'call_synced',
+          name: 'lookup',
+          args: { query: 'canonical', payload: 'x'.repeat(500_000) },
+        },
+      ],
+      response_metadata: {
+        output: [
+          {
+            type: 'function_call',
+            id: 'fc_synced',
+            call_id: 'call_synced',
+            name: 'lookup',
+            arguments: '{"query":"stale"}',
+          },
+        ],
+      },
+    });
+
+    const chat = _convertMessagesToOpenAIParams([message]);
+    const responses = _convertMessagesToOpenAIResponsesParams([message]);
+    const chatArguments = (
+      chat[0] as {
+        tool_calls: Array<{ function: { arguments: string } }>;
+      }
+    ).tool_calls[0].function.arguments;
+    const responseArguments = (
+      responses.find((item) => item.type === 'function_call') as {
+        arguments: string;
+      }
+    ).arguments;
+
+    expect(responseArguments).toBe(chatArguments);
+    expect(() => JSON.parse(responseArguments)).not.toThrow();
+    expect(
+      (
+        message.response_metadata.output as Array<{
+          arguments: string;
+        }>
+      )[0].arguments
+    ).toBe('{"query":"stale"}');
+  });
+
+  it('normalizes native Responses computer-call output screenshots', () => {
+    const screenshot = `data:image/png;base64,${'A'.repeat(2_000)}`;
+    const messages = [
+      new ToolMessage({
+        content: screenshot,
+        tool_call_id: 'call_computer_string',
+        additional_kwargs: { type: 'computer_call_output' },
+      }),
+      new ToolMessage({
+        content: [{ type: 'computer_screenshot', image_url: screenshot }],
+        tool_call_id: 'call_computer_structured',
+        additional_kwargs: { type: 'computer_call_output' },
+      }),
+      new ToolMessage({
+        content: [{ type: 'input_image', file_id: 'file_screenshot123' }],
+        tool_call_id: 'call_computer_file',
+        additional_kwargs: { type: 'computer_call_output' },
+      }),
+    ];
+
+    expect(_convertMessagesToOpenAIResponsesParams(messages)).toEqual([
+      {
+        type: 'computer_call_output',
+        call_id: 'call_computer_string',
+        output: { type: 'computer_screenshot', image_url: screenshot },
+      },
+      {
+        type: 'computer_call_output',
+        call_id: 'call_computer_structured',
+        output: { type: 'computer_screenshot', image_url: screenshot },
+      },
+      {
+        type: 'computer_call_output',
+        call_id: 'call_computer_file',
+        output: {
+          type: 'computer_screenshot',
+          file_id: 'file_screenshot123',
+        },
+      },
+    ]);
+  });
+
+  it('rejects malformed native Responses computer-call output', () => {
+    const message = new ToolMessage({
+      content: 'not a screenshot URL',
+      tool_call_id: 'call_computer_invalid',
+      additional_kwargs: { type: 'computer_call_output' },
+    });
+
+    expect(() => _convertMessagesToOpenAIResponsesParams([message])).toThrow(
+      'Invalid computer call output'
+    );
+  });
+
+  it('rejects a truncated data URI marked as a computer screenshot', () => {
+    const message = new ToolMessage({
+      content: 'data:image/png;base64,AAAA\n\n… [truncated: 1000 chars] …',
+      tool_call_id: 'call_computer_truncated',
+      additional_kwargs: { type: 'computer_call_output' },
+    });
+
+    expect(() => _convertMessagesToOpenAIResponsesParams([message])).toThrow(
+      'Invalid computer call output'
+    );
+  });
 });

package/src/llm/openrouter/index.ts

@@ -32,6 +32,7 @@ export interface ChatOpenRouterCallOptions
   include_reasoning?: boolean;
   reasoning?: OpenRouterReasoning;
   modelKwargs?: OpenAIChatInput['modelKwargs'];
+  useResponsesApi?: boolean;
   promptCache?: boolean;
   /**
    * Prompt-cache breakpoint TTL. Defaults to `'1h'` (extended cache) when
@@ -52,6 +53,7 @@ export type OpenRouterInvocationParams = Omit<
   'messages'
 > & {
   reasoning?: OpenRouterReasoning;
+  cache_control?: { type: 'ephemeral'; ttl?: '1h' };
 };
 
 type InvocationParamsExtra = {
@@ -150,6 +152,9 @@ export class ChatOpenRouter extends ChatOpenAI {
       modelKwargs: parentModelKwargs,
       includeReasoningDetails: true,
       convertReasoningDetailsToContent: true,
+      preserveToolCacheControl: true,
+      responsesPromptCache: _fields.promptCache,
+      responsesPromptCacheTtl: _fields.promptCacheTtl,
     });
 
     // Merge reasoning config: modelKwargs.reasoning < constructor reasoning
@@ -171,11 +176,16 @@ export class ChatOpenRouter extends ChatOpenAI {
     type MutableParams = Omit<
       OpenAIClient.Chat.ChatCompletionCreateParams,
       'messages'
-    > & { reasoning_effort?: string; reasoning?: OpenRouterReasoning };
+    > & {
+      reasoning_effort?: string;
+      reasoning?: OpenRouterReasoning;
+      cache_control?: { type: 'ephemeral'; ttl?: '1h' };
+    };
 
     const optionsWithDefaults = this._combineCallOptions(options);
+    const useResponsesApi = this._useResponsesApi(options);
     const params = (
-      this._useResponsesApi(options)
+      useResponsesApi
         ? this.responses.invocationParams(optionsWithDefaults)
         : this.completions.invocationParams(optionsWithDefaults, extra)
     ) as MutableParams;

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