@librechat/agents 3.4.7 → 3.5.1

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

@@ -1,561 +0,0 @@
-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<
-  ChatOpenRouterCallOptions &
-    Pick<OpenAIChatInput, 'model' | 'apiKey' | 'streamUsage'>
->;
-
-type RuntimeInvocationParams = {
-  reasoning?: OpenRouterReasoning;
-  reasoning_effort?: string;
-};
-
-class RuntimeInspectableChatOpenRouter extends ChatOpenRouter {
-  getRuntimeInvocationParams(): RuntimeInvocationParams {
-    return this.completions.invocationParams() as RuntimeInvocationParams;
-  }
-}
-
-function createRouter(overrides: CreateRouterOptions = {}): ChatOpenRouter {
-  return new ChatOpenRouter({
-    model: 'openrouter/test-model',
-    apiKey: 'test-key',
-    ...overrides,
-  });
-}
-
-describe('ChatOpenRouter reasoning handling', () => {
-  // ---------------------------------------------------------------
-  // 1. Constructor reasoning config
-  // ---------------------------------------------------------------
-  describe('constructor reasoning config', () => {
-    it('stores reasoning when passed directly', () => {
-      const router = createRouter({ reasoning: { effort: 'high' } });
-      const params = router.invocationParams();
-      expect(params.reasoning).toEqual({ effort: 'high' });
-    });
-  });
-
-  // ---------------------------------------------------------------
-  // 2. modelKwargs reasoning extraction
-  // ---------------------------------------------------------------
-  describe('modelKwargs reasoning extraction', () => {
-    it('extracts reasoning from modelKwargs and places it into params.reasoning', () => {
-      const router = createRouter({
-        modelKwargs: { reasoning: { effort: 'medium' } },
-      });
-      const params = router.invocationParams();
-      expect(params.reasoning).toEqual({ effort: 'medium' });
-    });
-
-    it('does not leak reasoning into modelKwargs that reach the parent', () => {
-      const router = createRouter({
-        modelKwargs: {
-          reasoning: { effort: 'medium' },
-        },
-      });
-      const params = router.invocationParams();
-      // reasoning should be the structured OpenRouter object, not buried in modelKwargs
-      expect(params.reasoning).toEqual({ effort: 'medium' });
-    });
-  });
-
-  // ---------------------------------------------------------------
-  // 3. Reasoning merge precedence
-  // ---------------------------------------------------------------
-  describe('reasoning merge precedence', () => {
-    it('constructor reasoning overrides modelKwargs.reasoning', () => {
-      const router = createRouter({
-        reasoning: { effort: 'high' },
-        modelKwargs: { reasoning: { effort: 'low' } },
-      });
-      const params = router.invocationParams();
-      expect(params.reasoning).toEqual({ effort: 'high' });
-    });
-
-    it('merges non-overlapping keys from modelKwargs.reasoning and constructor reasoning', () => {
-      const router = createRouter({
-        reasoning: { effort: 'high' },
-        modelKwargs: { reasoning: { max_tokens: 5000 } },
-      });
-      const params = router.invocationParams();
-      expect(params.reasoning).toEqual({ effort: 'high', max_tokens: 5000 });
-    });
-  });
-
-  // ---------------------------------------------------------------
-  // 4. invocationParams output
-  // ---------------------------------------------------------------
-  describe('invocationParams output', () => {
-    it('includes reasoning object in params', () => {
-      const router = createRouter({ reasoning: { effort: 'high' } });
-      const params = router.invocationParams();
-      expect(params.reasoning).toBeDefined();
-      expect(params.reasoning).toEqual({ effort: 'high' });
-    });
-
-    it('does NOT include reasoning_effort in params', () => {
-      const router = createRouter({ reasoning: { effort: 'high' } });
-      const params = router.invocationParams();
-      expect(params.reasoning_effort).toBeUndefined();
-    });
-
-    it('passes reasoning to the runtime completions delegate', () => {
-      const router = new RuntimeInspectableChatOpenRouter({
-        model: 'openrouter/test-model',
-        apiKey: 'test-key',
-        reasoning: { max_tokens: 1024 },
-      });
-      const params = router.getRuntimeInvocationParams();
-      expect(params.reasoning).toEqual({ max_tokens: 1024 });
-      expect(params.reasoning_effort).toBeUndefined();
-    });
-
-    it('passes legacy include_reasoning to the runtime completions delegate', () => {
-      const router = new RuntimeInspectableChatOpenRouter({
-        model: 'openrouter/test-model',
-        apiKey: 'test-key',
-        include_reasoning: true,
-      });
-      const params = router.getRuntimeInvocationParams();
-      expect(params.reasoning).toEqual({ enabled: true });
-      expect(params.reasoning_effort).toBeUndefined();
-    });
-
-    it('does not include reasoning when none is configured', () => {
-      const router = createRouter();
-      const params = router.invocationParams();
-      expect(params.reasoning).toBeUndefined();
-      expect(params.reasoning_effort).toBeUndefined();
-    });
-
-    it('preserves streaming extras from parent invocation params', () => {
-      const router = createRouter({ streamUsage: true });
-      const params = router.invocationParams(undefined, { streaming: true });
-      expect(params.stream_options).toEqual({ include_usage: true });
-    });
-  });
-
-  // ---------------------------------------------------------------
-  // 5. Legacy include_reasoning
-  // ---------------------------------------------------------------
-  describe('legacy include_reasoning', () => {
-    it('produces { enabled: true } when only include_reasoning is true', () => {
-      const router = createRouter({ include_reasoning: true });
-      const params = router.invocationParams();
-      expect(params.reasoning).toEqual({ enabled: true });
-    });
-
-    it('does not produce reasoning when include_reasoning is false', () => {
-      const router = createRouter({ include_reasoning: false });
-      const params = router.invocationParams();
-      expect(params.reasoning).toBeUndefined();
-    });
-  });
-
-  // ---------------------------------------------------------------
-  // 6. Legacy include_reasoning ignored when reasoning is provided
-  // ---------------------------------------------------------------
-  describe('legacy include_reasoning ignored when reasoning provided', () => {
-    it('reasoning wins over include_reasoning', () => {
-      const router = createRouter({
-        reasoning: { effort: 'medium' },
-        include_reasoning: true,
-      });
-      const params = router.invocationParams();
-      // Should use the structured reasoning, NOT fall back to { enabled: true }
-      expect(params.reasoning).toEqual({ effort: 'medium' });
-    });
-
-    it('reasoning from modelKwargs also wins over include_reasoning', () => {
-      const router = createRouter({
-        modelKwargs: { reasoning: { effort: 'low' } },
-        include_reasoning: true,
-      });
-      const params = router.invocationParams();
-      expect(params.reasoning).toEqual({ effort: 'low' });
-    });
-  });
-
-  // ---------------------------------------------------------------
-  // 7. Various effort levels (OpenRouter-specific)
-  // ---------------------------------------------------------------
-  describe('various effort levels', () => {
-    const efforts: Array<{
-      effort: OpenRouterReasoning['effort'];
-    }> = [
-      { effort: 'xhigh' },
-      { effort: 'none' },
-      { effort: 'minimal' },
-      { effort: 'high' },
-      { effort: 'medium' },
-      { effort: 'low' },
-    ];
-
-    it.each(efforts)('supports effort level "$effort"', ({ effort }) => {
-      const router = createRouter({ reasoning: { effort } });
-      const params = router.invocationParams();
-      expect(params.reasoning).toEqual({ effort });
-      expect(params.reasoning_effort).toBeUndefined();
-    });
-  });
-
-  // ---------------------------------------------------------------
-  // 8. max_tokens reasoning
-  // ---------------------------------------------------------------
-  describe('max_tokens reasoning', () => {
-    it('passes max_tokens in reasoning object', () => {
-      const router = createRouter({
-        reasoning: { max_tokens: 8000 },
-      });
-      const params = router.invocationParams();
-      expect(params.reasoning).toEqual({ max_tokens: 8000 });
-    });
-
-    it('combines max_tokens with effort', () => {
-      const router = createRouter({
-        reasoning: { effort: 'high', max_tokens: 8000 },
-      });
-      const params = router.invocationParams();
-      expect(params.reasoning).toEqual({ effort: 'high', max_tokens: 8000 });
-      expect(params.reasoning_effort).toBeUndefined();
-    });
-  });
-
-  // ---------------------------------------------------------------
-  // 9. exclude reasoning
-  // ---------------------------------------------------------------
-  describe('exclude reasoning', () => {
-    it('passes exclude flag in reasoning object', () => {
-      const router = createRouter({
-        reasoning: { effort: 'high', exclude: true },
-      });
-      const params = router.invocationParams();
-      expect(params.reasoning).toEqual({ effort: 'high', exclude: true });
-    });
-
-    it('supports exclude without effort', () => {
-      const router = createRouter({
-        reasoning: { exclude: true },
-      });
-      const params = router.invocationParams();
-      expect(params.reasoning).toEqual({ exclude: true });
-    });
-  });
-});
-
-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/llm/openrouter/toolCache.test.ts

@@ -1,134 +0,0 @@
-import { tool } from '@langchain/core/tools';
-import type { GraphTools } from '@/types';
-import { partitionAndMarkOpenRouterToolCache } from './toolCache';
-
-type OpenRouterTool = {
-  type: 'function';
-  function: {
-    name: string;
-    description?: string;
-    parameters?: object;
-  };
-  cache_control?: { type: 'ephemeral'; ttl?: '1h' };
-  defer_loading?: boolean;
-};
-
-function createOpenAITool(name: string): OpenRouterTool {
-  return {
-    type: 'function',
-    function: {
-      name,
-      description: `${name} description`,
-      parameters: {
-        type: 'object',
-        properties: {},
-      },
-    },
-  };
-}
-
-describe('partitionAndMarkOpenRouterToolCache', () => {
-  it('marks the last static OpenRouter tool before deferred tools', () => {
-    const tools = [
-      createOpenAITool('static_one'),
-      createOpenAITool('static_two'),
-      createOpenAITool('dynamic_one'),
-    ] as GraphTools;
-
-    const result = partitionAndMarkOpenRouterToolCache(
-      tools,
-      (name) => name === 'dynamic_one'
-    ) as OpenRouterTool[];
-
-    expect(result.map((entry) => entry.function.name)).toEqual([
-      'static_one',
-      'static_two',
-      'dynamic_one',
-    ]);
-    expect(result[0]).not.toHaveProperty('cache_control');
-    expect(result[1].cache_control).toEqual({ type: 'ephemeral' });
-    expect(result[2]).not.toHaveProperty('cache_control');
-  });
-
-  it('converts LangChain tools to OpenAI tools before adding cache control', () => {
-    const staticTool = tool(async () => 'static', {
-      name: 'static_tool',
-      description: 'Static tool',
-      schema: {
-        type: 'object',
-        properties: {},
-      },
-    });
-    const dynamicTool = tool(async () => 'dynamic', {
-      name: 'dynamic_tool',
-      description: 'Dynamic tool',
-      schema: {
-        type: 'object',
-        properties: {},
-      },
-    });
-
-    const result = partitionAndMarkOpenRouterToolCache(
-      [dynamicTool, staticTool] as GraphTools,
-      (name) => name === 'dynamic_tool'
-    ) as OpenRouterTool[];
-
-    expect(result.map((entry) => entry.function.name)).toEqual([
-      'static_tool',
-      'dynamic_tool',
-    ]);
-    expect(result[0].cache_control).toEqual({ type: 'ephemeral' });
-    expect(result[1]).not.toHaveProperty('cache_control');
-  });
-
-  it('stamps the resolved 1h ttl on the last static tool', () => {
-    const result = partitionAndMarkOpenRouterToolCache(
-      [
-        createOpenAITool('static_one'),
-        createOpenAITool('static_two'),
-      ] as GraphTools,
-      () => false,
-      '1h'
-    ) as OpenRouterTool[];
-
-    expect(result[1].cache_control).toEqual({ type: 'ephemeral', ttl: '1h' });
-    expect(result[0]).not.toHaveProperty('cache_control');
-  });
-
-  it('omits ttl for the 5m legacy default', () => {
-    const result = partitionAndMarkOpenRouterToolCache(
-      [createOpenAITool('only_static')] as GraphTools,
-      () => false,
-      '5m'
-    ) as OpenRouterTool[];
-
-    expect(result[0].cache_control).toEqual({ type: 'ephemeral' });
-  });
-
-  it('strips a stale marker off an earlier static tool', () => {
-    const earlier = createOpenAITool('static_one');
-    earlier.cache_control = { type: 'ephemeral' };
-    const result = partitionAndMarkOpenRouterToolCache(
-      [earlier, createOpenAITool('static_two')] as GraphTools,
-      () => false,
-      '1h'
-    ) as OpenRouterTool[];
-
-    // No stale 5m marker survives ahead of the resolved 1h breakpoint.
-    expect(result[0]).not.toHaveProperty('cache_control');
-    expect(result[1].cache_control).toEqual({ type: 'ephemeral', ttl: '1h' });
-  });
-
-  it('strips a stale marker off a deferred tool', () => {
-    const deferred = createOpenAITool('deferred_one');
-    deferred.cache_control = { type: 'ephemeral' };
-    const result = partitionAndMarkOpenRouterToolCache(
-      [createOpenAITool('static_one'), deferred] as GraphTools,
-      (name) => name === 'deferred_one',
-      '1h'
-    ) as OpenRouterTool[];
-
-    expect(result[0].cache_control).toEqual({ type: 'ephemeral', ttl: '1h' });
-    expect(result[1]).not.toHaveProperty('cache_control');
-  });
-});