@librechat/agents 3.1.82 → 3.1.84

package/dist/types/agents/AgentContext.d.ts

@@ -186,13 +186,15 @@ export declare class AgentContext {
     /**
      * Builds instructions text for tools that are ONLY callable via programmatic code execution.
      * These tools cannot be called directly by the LLM but are available through the
-     * run_tools_with_code tool.
+     * configured programmatic tool.
      *
      * Includes:
      * - Code_execution-only tools that are NOT deferred
      * - Code_execution-only tools that ARE deferred but have been discovered via tool search
      */
     private buildProgrammaticOnlyToolsInstructions;
+    private getProgrammaticToolInstructionTarget;
+    private hasAvailableTool;
     /**
      * Gets the system runnable, creating it lazily if needed.
      * Includes stable instructions, dynamic additional instructions, and
@@ -227,8 +229,10 @@ export declare class AgentContext {
      */
     private buildSystemRunnable;
     private buildSummaryHumanMessage;
-    private buildOpenRouterDynamicTail;
-    private insertAfterFirstMessage;
+    private buildPromptCacheDynamicTail;
+    private buildBodyWithPromptCacheDynamicTail;
+    private getPromptCacheDynamicTailIndex;
+    private addStablePromptCacheMarkers;
     private getPromptCacheProvider;
     private hasBedrockPromptCache;
     private buildSystemMessage;

package/dist/types/agents/__tests__/promptCacheLiveHelpers.d.ts

@@ -1,7 +1,9 @@
 import type { UsageMetadata } from '@langchain/core/messages';
+import type { ClientOptions } from '@langchain/openai';
 import type * as t from '@/types';
 import { Providers } from '@/common';
-type LivePromptCacheProvider = Providers.ANTHROPIC | Providers.BEDROCK;
+import type { ChatOpenRouterInput } from '@/llm/openrouter';
+type LivePromptCacheProvider = Providers.ANTHROPIC | Providers.BEDROCK | Providers.OPENROUTER;
 type PromptCacheExpectedSystemBlock = {
     type: 'text';
     text: string;
@@ -13,7 +15,9 @@ type PromptCacheExpectedSystemBlock = {
         type: 'default';
     };
 };
-type LivePromptCacheClientOptions = t.ClientOptions | t.BedrockAnthropicClientOptions;
+type LivePromptCacheClientOptions = t.ClientOptions | t.BedrockAnthropicClientOptions | (ChatOpenRouterInput & {
+    configuration?: ClientOptions;
+});
 export declare function buildStableInstructions({ nonce, providerLabel, }: {
     nonce: string;
     providerLabel: string;

package/dist/types/messages/cache.d.ts

@@ -13,6 +13,7 @@ type MessageWithContent = {
  * @returns - A new array of message objects with cache control added.
  */
 export declare function addCacheControl<T extends AnthropicMessage | BaseMessage>(messages: T[]): T[];
+export declare function addCacheControlToStablePrefixMessages<T extends AnthropicMessage | BaseMessage>(messages: T[], maxCachePoints: number): T[];
 /**
  * Removes all Anthropic cache_control fields from messages
  * Used when switching from Anthropic to Bedrock provider

package/dist/types/tools/CodeExecutor.d.ts

@@ -25,6 +25,11 @@ export declare const CodeExecutionToolSchema: {
     };
     readonly required: readonly ["lang", "code"];
 };
+export declare function resolveCodeApiAuthHeaders(authHeaders?: t.CodeApiAuthHeaders): Promise<t.CodeApiAuthHeaderMap>;
+export declare function buildCodeApiHttpErrorMessage(method: string, endpoint: string, response: {
+    status: number;
+    text: () => Promise<string>;
+}): Promise<string>;
 export declare const CodeExecutionToolDescription: string;
 export declare const CodeExecutionToolName = Constants.EXECUTE_CODE;
 export declare const CodeExecutionToolDefinition: {

package/dist/types/tools/ProgrammaticToolCalling.d.ts

@@ -43,6 +43,15 @@ export declare const ProgrammaticToolCallingDefinition: {
         readonly required: readonly ["code"];
     };
 };
+export type FetchSessionFilesScope = {
+    kind: 'skill';
+    id: string;
+    version: number;
+} | {
+    kind: 'agent' | 'user';
+    id: string;
+    version?: never;
+};
 /**
  * Normalizes a tool name to Python identifier format.
  * Must match the Code API's `normalizePythonFunctionName` exactly:
@@ -76,10 +85,12 @@ export declare function filterToolsByUsage(toolDefs: t.LCTool[], code: string, d
  * Files are returned as CodeEnvFile references to be included in the request.
  * @param baseUrl - The base URL for the Code API
  * @param sessionId - The session ID to fetch files from
+ * @param scope - Resource scope used by CodeAPI to authorize the session
  * @param proxy - Optional HTTP proxy URL
  * @returns Array of CodeEnvFile references, or empty array if fetch fails
  */
-export declare function fetchSessionFiles(baseUrl: string, sessionId: string, proxy?: string): Promise<t.CodeEnvFile[]>;
+export declare function fetchSessionFiles(baseUrl: string, sessionId: string, proxy?: string, authHeaders?: t.CodeApiAuthHeaders): Promise<t.CodeEnvFile[]>;
+export declare function fetchSessionFiles(baseUrl: string, sessionId: string, scope: FetchSessionFilesScope, proxyOrAuthHeaders?: string | t.CodeApiAuthHeaders, authHeaders?: t.CodeApiAuthHeaders): Promise<t.CodeEnvFile[]>;
 /**
  * Makes an HTTP request to the Code API.
  * @param endpoint - The API endpoint URL
@@ -87,7 +98,7 @@ export declare function fetchSessionFiles(baseUrl: string, sessionId: string, pr
  * @param proxy - Optional HTTP proxy URL
  * @returns The parsed API response
  */
-export declare function makeRequest(endpoint: string, body: Record<string, unknown>, proxy?: string): Promise<t.ProgrammaticExecutionResponse>;
+export declare function makeRequest(endpoint: string, body: Record<string, unknown>, proxy?: string, authHeaders?: t.CodeApiAuthHeaders): Promise<t.ProgrammaticExecutionResponse>;
 /**
  * Unwraps tool responses that may be formatted as tuples or content blocks.
  * MCP tools return [content, artifacts], we need to extract the raw data.
@@ -104,7 +115,7 @@ export declare function unwrapToolResponse(result: unknown, isMCPTool: boolean):
  * @param toolMap - Map of tool names to executable tools
  * @returns Array of tool results
  */
-export declare function executeTools(toolCalls: t.PTCToolCall[], toolMap: t.ToolMap): Promise<t.PTCToolResult[]>;
+export declare function executeTools(toolCalls: t.PTCToolCall[], toolMap: t.ToolMap, programmaticToolName?: Constants): Promise<t.PTCToolResult[]>;
 /**
  * Formats the completed response for the agent.
  *

package/dist/types/types/tools.d.ts

@@ -205,7 +205,11 @@ export type CodeExecutionToolParams = undefined | {
     session_id?: string;
     user_id?: string;
     files?: CodeEnvFile[];
+    /** Optional host-supplied Code API auth headers. */
+    authHeaders?: CodeApiAuthHeaders;
 };
+export type CodeApiAuthHeaderMap = Record<string, string>;
+export type CodeApiAuthHeaders = CodeApiAuthHeaderMap | (() => CodeApiAuthHeaderMap | Promise<CodeApiAuthHeaderMap>);
 export type FileRef = {
     /**
      * Storage file id (the per-file uuid). See `CodeEnvFile.id` for
@@ -825,6 +829,8 @@ export type ProgrammaticToolCallingParams = {
     proxy?: string;
     /** Enable debug logging (or set PTC_DEBUG=true env var) */
     debug?: boolean;
+    /** Optional host-supplied Code API auth headers. */
+    authHeaders?: CodeApiAuthHeaders;
 };
 /**
  * Tracks code execution session state for automatic file persistence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.82",
+  "version": "3.1.84",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/agents/AgentContext.ts

@@ -13,10 +13,14 @@ import {
   ANTHROPIC_TOOL_TOKEN_MULTIPLIER,
   DEFAULT_TOOL_TOKEN_MULTIPLIER,
   ContentTypes,
+  Constants,
   Providers,
 } from '@/common';
 import { createSchemaOnlyTools } from '@/tools/schema';
-import { addCacheControl } from '@/messages/cache';
+import {
+  addCacheControl,
+  addCacheControlToStablePrefixMessages,
+} from '@/messages/cache';
 import { DEFAULT_RESERVE_RATIO } from '@/messages';
 import { toJsonSchema } from '@/utils/schema';
 
@@ -386,7 +390,7 @@ export class AgentContext {
   /**
    * Builds instructions text for tools that are ONLY callable via programmatic code execution.
    * These tools cannot be called directly by the LLM but are available through the
-   * run_tools_with_code tool.
+   * configured programmatic tool.
    *
    * Includes:
    * - Code_execution-only tools that are NOT deferred
@@ -413,6 +417,7 @@ export class AgentContext {
 
     if (programmaticOnlyTools.length === 0) return '';
 
+    const programmaticTool = this.getProgrammaticToolInstructionTarget();
     const toolDescriptions = programmaticOnlyTools
       .map((tool) => {
         let desc = `- **${tool.name}**`;
@@ -428,12 +433,39 @@ export class AgentContext {
 
     return (
       '\n\n## Programmatic-Only Tools\n\n' +
-      'The following tools are available exclusively through the `run_tools_with_code` tool. ' +
-      'You cannot call these tools directly; instead, use `run_tools_with_code` with Python code that invokes them.\n\n' +
+      `The following tools are available exclusively through the \`${programmaticTool.name}\` tool. ` +
+      `You cannot call these tools directly; instead, use \`${programmaticTool.name}\` with ${programmaticTool.language} code that invokes them.\n\n` +
       toolDescriptions
     );
   }
 
+  private getProgrammaticToolInstructionTarget(): {
+    name: string;
+    language: 'bash' | 'Python';
+    } {
+    if (this.hasAvailableTool(Constants.BASH_PROGRAMMATIC_TOOL_CALLING)) {
+      return {
+        name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
+        language: 'bash',
+      };
+    }
+
+    if (this.hasAvailableTool(Constants.PROGRAMMATIC_TOOL_CALLING)) {
+      return { name: Constants.PROGRAMMATIC_TOOL_CALLING, language: 'Python' };
+    }
+
+    return { name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING, language: 'bash' };
+  }
+
+  private hasAvailableTool(name: string): boolean {
+    if (this.toolDefinitions?.some((tool) => tool.name === name)) return true;
+    if (this.tools?.some((tool) => 'name' in tool && tool.name === name)) {
+      return true;
+    }
+    if (this.toolMap?.has(name)) return true;
+    return this.toolRegistry?.has(name) === true;
+  }
+
   /**
    * Gets the system runnable, creating it lazily if needed.
    * Includes stable instructions, dynamic additional instructions, and
@@ -584,24 +616,24 @@ export class AgentContext {
     }
 
     const promptCacheProvider = this.getPromptCacheProvider();
-    const shouldMoveOpenRouterDynamicInstructions =
-      promptCacheProvider === Providers.OPENROUTER &&
+    const shouldMoveDynamicInstructions =
+      promptCacheProvider != null &&
       stableInstructions !== '' &&
       dynamicInstructions !== '';
     const systemMessage = this.buildSystemMessage({
       stableInstructions,
       dynamicInstructions,
       promptCacheProvider,
+      shouldMoveDynamicInstructions,
     });
 
     if (this.tokenCounter) {
       this.systemMessageTokens = systemMessage
         ? this.tokenCounter(systemMessage)
         : 0;
-      this.dynamicInstructionTokens =
-        shouldMoveOpenRouterDynamicInstructions
-          ? this.tokenCounter(new HumanMessage(dynamicInstructions))
-          : 0;
+      this.dynamicInstructionTokens = shouldMoveDynamicInstructions
+        ? this.tokenCounter(new HumanMessage(dynamicInstructions))
+        : 0;
     }
 
     return RunnableLambda.from((messages: BaseMessage[]) => {
@@ -616,16 +648,20 @@ export class AgentContext {
         this.summaryText !== '';
 
       const bodyWithSummary =
-        hasSummaryBody && promptCacheProvider !== Providers.OPENROUTER
+        hasSummaryBody && promptCacheProvider == null
           ? [this.buildSummaryHumanMessage(promptCacheProvider), ...messages]
           : messages;
-      const dynamicTail = this.buildOpenRouterDynamicTail({
+      const dynamicTail = this.buildPromptCacheDynamicTail({
         dynamicInstructions,
         hasSummaryBody,
         promptCacheProvider,
-        shouldMoveOpenRouterDynamicInstructions,
+        shouldMoveDynamicInstructions,
       });
-      let body = this.insertAfterFirstMessage(bodyWithSummary, dynamicTail);
+      let body = this.buildBodyWithPromptCacheDynamicTail(
+        bodyWithSummary,
+        dynamicTail,
+        promptCacheProvider
+      );
 
       if (
         promptCacheProvider != null &&
@@ -662,22 +698,22 @@ export class AgentContext {
     });
   }
 
-  private buildOpenRouterDynamicTail({
+  private buildPromptCacheDynamicTail({
     dynamicInstructions,
     hasSummaryBody,
     promptCacheProvider,
-    shouldMoveOpenRouterDynamicInstructions,
+    shouldMoveDynamicInstructions,
   }: {
     dynamicInstructions: string;
     hasSummaryBody: boolean;
     promptCacheProvider: PromptCacheProvider | undefined;
-    shouldMoveOpenRouterDynamicInstructions: boolean;
+    shouldMoveDynamicInstructions: boolean;
   }): BaseMessage[] {
-    if (promptCacheProvider !== Providers.OPENROUTER) {
+    if (promptCacheProvider == null) {
       return [];
     }
 
-    const dynamicTail = shouldMoveOpenRouterDynamicInstructions
+    const dynamicTail = shouldMoveDynamicInstructions
       ? [new HumanMessage(dynamicInstructions)]
       : [];
 
@@ -685,22 +721,59 @@ export class AgentContext {
       return dynamicTail;
     }
 
-    return [...dynamicTail, this.buildSummaryHumanMessage(promptCacheProvider)];
+    return [...dynamicTail, this.buildSummaryHumanMessage(undefined)];
   }
 
-  private insertAfterFirstMessage(
+  private buildBodyWithPromptCacheDynamicTail(
     messages: BaseMessage[],
-    tail: BaseMessage[]
+    tail: BaseMessage[],
+    promptCacheProvider: PromptCacheProvider | undefined
   ): BaseMessage[] {
     if (tail.length === 0) {
       return messages;
     }
 
-    if (messages.length === 0) {
-      return tail;
+    const tailIndex = this.getPromptCacheDynamicTailIndex(
+      messages,
+      promptCacheProvider
+    );
+    const stablePrefix = messages.slice(0, tailIndex);
+    const trailingMessages = messages.slice(tailIndex);
+    const cacheablePrefix = this.addStablePromptCacheMarkers(stablePrefix);
+
+    return [...cacheablePrefix, ...tail, ...trailingMessages];
+  }
+
+  private getPromptCacheDynamicTailIndex(
+    messages: BaseMessage[],
+    promptCacheProvider: PromptCacheProvider | undefined
+  ): number {
+    const lastIndex = messages.length - 1;
+
+    if (lastIndex < 0) {
+      return 0;
+    }
+
+    if (promptCacheProvider === Providers.OPENROUTER && messages.length === 1) {
+      return messages.length;
+    }
+
+    if (messages[lastIndex].getType() === 'human') {
+      return lastIndex;
     }
 
-    return [messages[0], ...tail, ...messages.slice(1)];
+    return messages.length;
+  }
+
+  private addStablePromptCacheMarkers(messages: BaseMessage[]): BaseMessage[] {
+    if (messages.length <= 1) {
+      return messages;
+    }
+
+    return [
+      messages[0],
+      ...addCacheControlToStablePrefixMessages(messages.slice(1), 2),
+    ];
   }
 
   private getPromptCacheProvider(): PromptCacheProvider | undefined {
@@ -739,10 +812,12 @@ export class AgentContext {
     stableInstructions,
     dynamicInstructions,
     promptCacheProvider,
+    shouldMoveDynamicInstructions,
   }: {
     stableInstructions: string;
     dynamicInstructions: string;
     promptCacheProvider: PromptCacheProvider | undefined;
+    shouldMoveDynamicInstructions: boolean;
   }): SystemMessage | undefined {
     if (!stableInstructions && !dynamicInstructions) {
       return undefined;
@@ -757,16 +832,13 @@ export class AgentContext {
           cache_control: { type: 'ephemeral' },
         });
       }
-      if (dynamicInstructions) {
+      if (dynamicInstructions && !shouldMoveDynamicInstructions) {
         content.push({ type: 'text', text: dynamicInstructions });
       }
       return new SystemMessage({ content } as BaseMessageFields);
     }
 
-    if (
-      promptCacheProvider === Providers.OPENROUTER &&
-      !stableInstructions
-    ) {
+    if (promptCacheProvider === Providers.OPENROUTER && !stableInstructions) {
       return new SystemMessage(dynamicInstructions);
     }
 

package/src/agents/__tests__/AgentContext.anthropic.live.test.ts

@@ -77,10 +77,6 @@ describeIfLive('AgentContext Anthropic prompt cache live API', () => {
           text: stableInstructions,
           cache_control: { type: 'ephemeral' },
         },
-        {
-          type: 'text',
-          text: firstDynamicInstructions,
-        },
       ],
     });
 

package/src/agents/__tests__/AgentContext.openrouter.live.test.ts

@@ -0,0 +1,128 @@
+// src/agents/__tests__/AgentContext.openrouter.live.test.ts
+/**
+ * Live OpenRouter prompt-cache verification.
+ *
+ * Run with:
+ * RUN_OPENROUTER_PROMPT_CACHE_LIVE_TESTS=1 OPENROUTER_API_KEY=... npm test -- AgentContext.openrouter.live.test.ts --runInBand
+ */
+import { config as dotenvConfig } from 'dotenv';
+dotenvConfig({ path: process.env.DOTENV_CONFIG_PATH ?? '.env' });
+
+import { describe, expect, it } from '@jest/globals';
+import type { ClientOptions } from '@langchain/openai';
+import {
+  runLiveTurn,
+  assertSystemPayloadShape,
+  buildDynamicInstructions,
+  buildStableInstructions,
+  waitForCachePropagation,
+} from './promptCacheLiveHelpers';
+import type { ChatOpenRouterInput } from '@/llm/openrouter';
+import { Providers } from '@/common';
+
+const apiKey = process.env.OPENROUTER_API_KEY ?? process.env.OPENROUTER_KEY;
+const shouldRunLive =
+  process.env.RUN_OPENROUTER_PROMPT_CACHE_LIVE_TESTS === '1' &&
+  apiKey != null &&
+  apiKey !== '';
+
+const describeIfLive = shouldRunLive ? describe : describe.skip;
+
+const model =
+  process.env.OPENROUTER_PROMPT_CACHE_MODEL ?? 'anthropic/claude-sonnet-4.6';
+const providerLabel = 'OpenRouter';
+type OpenRouterLiveClientOptions = ChatOpenRouterInput & {
+  configuration?: ClientOptions;
+};
+
+function createClientOptions(): OpenRouterLiveClientOptions {
+  if (apiKey == null || apiKey === '') {
+    throw new Error('OPENROUTER_API_KEY is required');
+  }
+
+  const reasoning = model.startsWith('google/gemini-3')
+    ? { max_tokens: 16 }
+    : undefined;
+
+  return {
+    model,
+    apiKey,
+    temperature: 0,
+    maxTokens: 256,
+    streaming: true,
+    streamUsage: true,
+    promptCache: true,
+    configuration: {
+      baseURL:
+        process.env.OPENROUTER_BASE_URL ?? 'https://openrouter.ai/api/v1',
+      defaultHeaders: {
+        'HTTP-Referer': 'https://librechat.ai',
+        'X-Title': 'LibreChat OpenRouter Prompt Cache Live Test',
+      },
+    },
+    ...(reasoning != null ? { reasoning } : {}),
+  };
+}
+
+describeIfLive('AgentContext OpenRouter prompt cache live API', () => {
+  it('keeps dynamic instructions outside the cached system prefix', async () => {
+    const nonce = `agent-openrouter-cache-live-${Date.now()}`;
+    const clientOptions = createClientOptions();
+    const stableInstructions = buildStableInstructions({
+      nonce,
+      providerLabel,
+    });
+    const firstDynamicInstructions = buildDynamicInstructions({
+      marker: 'alpha',
+      tailDescription:
+        'The Dynamic Marker line is runtime context and must remain outside the cached prefix.',
+    });
+    const secondDynamicInstructions = buildDynamicInstructions({
+      marker: 'bravo',
+      tailDescription:
+        'The Dynamic Marker line is runtime context and must remain outside the cached prefix.',
+    });
+
+    await assertSystemPayloadShape({
+      agentId: 'live-openrouter-cache-shape-check',
+      provider: Providers.OPENROUTER,
+      clientOptions,
+      stableInstructions,
+      dynamicInstructions: firstDynamicInstructions,
+      expectedContent: [
+        {
+          type: 'text',
+          text: stableInstructions,
+          cache_control: { type: 'ephemeral' },
+        },
+      ],
+    });
+
+    const first = await runLiveTurn({
+      provider: Providers.OPENROUTER,
+      providerLabel,
+      clientOptions,
+      runId: `${nonce}-first`,
+      threadId: `${nonce}-thread`,
+      stableInstructions,
+      dynamicInstructions: firstDynamicInstructions,
+    });
+
+    expect(first.text.toLowerCase()).toContain('alpha');
+
+    await waitForCachePropagation();
+
+    const second = await runLiveTurn({
+      provider: Providers.OPENROUTER,
+      providerLabel,
+      clientOptions,
+      runId: `${nonce}-second`,
+      threadId: `${nonce}-thread`,
+      stableInstructions,
+      dynamicInstructions: secondDynamicInstructions,
+    });
+
+    expect(second.text.toLowerCase()).toContain('bravo');
+    expect(second.usage.input_token_details?.cache_read).toBeGreaterThan(0);
+  }, 120_000);
+});