@librechat/agents 3.1.81 → 3.1.83

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

@@ -54,6 +54,8 @@ export declare class AgentContext {
     tokenCounter?: t.TokenCounter;
     /** Token count for the system message (instructions text). */
     systemMessageTokens: number;
+    /** Token count for instruction text emitted outside the system message. */
+    dynamicInstructionTokens: number;
     /** Token count for tool schemas only. */
     toolSchemaTokens: number;
     /** Running calibration ratio from the pruner — persisted across runs via contextMeta. */
@@ -224,7 +226,12 @@ export declare class AgentContext {
      * Only called when content has actually changed.
      */
     private buildSystemRunnable;
-    private hasAnthropicPromptCache;
+    private buildSummaryHumanMessage;
+    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/llm/openrouter/index.d.ts

@@ -15,6 +15,7 @@ export interface ChatOpenRouterCallOptions extends Omit<ChatOpenAICallOptions, '
     include_reasoning?: boolean;
     reasoning?: OpenRouterReasoning;
     modelKwargs?: OpenAIChatInput['modelKwargs'];
+    promptCache?: boolean;
 }
 export type ChatOpenRouterInput = Partial<ChatOpenRouterCallOptions & OpenAIChatInput>;
 /** invocationParams return type extended with OpenRouter reasoning */

package/dist/types/llm/openrouter/toolCache.d.ts

@@ -0,0 +1,2 @@
+import type { GraphTools } from '@/types';
+export declare function partitionAndMarkOpenRouterToolCache(tools: GraphTools | undefined, isDeferred: (toolName: string) => boolean): GraphTools | undefined;

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/ToolNode.d.ts

@@ -152,6 +152,11 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * `createLocalCodingToolBundle()` use.
      */
     getFileCheckpointer(): t.LocalFileCheckpointer | undefined;
+    private getRegisteredHandoffNames;
+    private hasRegisteredHandoffTool;
+    private getHandoffToolNameSuggestion;
+    private shouldHandleUnknownHandoffLocally;
+    private getUnknownToolErrorMessage;
     /**
      * Flush the per-Run direct-path turn cache. Called by the Graph at
      * end-of-Run via `clearHeavyState`. The map intentionally survives

package/dist/types/types/run.d.ts

@@ -195,6 +195,8 @@ export type TokenBudgetBreakdown = {
     instructionTokens: number;
     /** Tokens from the system message text alone. */
     systemMessageTokens: number;
+    /** Tokens from instruction text emitted outside the system message. */
+    dynamicInstructionTokens: number;
     /** Tokens from tool schema definitions. */
     toolSchemaTokens: number;
     /** Tokens from the conversation summary. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.81",
+  "version": "3.1.83",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -171,6 +171,7 @@
     "start:dev": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/main.ts",
     "supervised": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/supervised.ts --provider anthropic --name Jo --location \"New York, NY\"",
     "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "test:live:handoffs": "RUN_HANDOFF_LIVE_TESTS=1 NODE_OPTIONS='--experimental-vm-modules' jest src/specs/agent-handoffs.live.test.ts --runInBand",
     "test:memory": "NODE_OPTIONS='--expose-gc' npx jest src/specs/title.memory-leak.test.ts",
     "test:all": "npm test -- --testPathIgnorePatterns=title.memory-leak.test.ts && npm run test:memory",
     "reinstall": "npm run clean && npm ci && rm -rf ./dist && npm run build",

package/src/agents/AgentContext.ts

@@ -16,7 +16,10 @@ import {
   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';
 
@@ -30,6 +33,8 @@ type AgentSystemContentBlock =
   | AgentSystemTextBlock
   | { cachePoint: { type: 'default' } };
 
+type PromptCacheProvider = Providers.ANTHROPIC | Providers.OPENROUTER;
+
 /**
  * Encapsulates agent-specific state that can vary between agents in a multi-agent system
  */
@@ -177,6 +182,8 @@ export class AgentContext {
   tokenCounter?: t.TokenCounter;
   /** Token count for the system message (instructions text). */
   systemMessageTokens: number = 0;
+  /** Token count for instruction text emitted outside the system message. */
+  dynamicInstructionTokens: number = 0;
   /** Token count for tool schemas only. */
   toolSchemaTokens: number = 0;
   /** Running calibration ratio from the pruner — persisted across runs via contextMeta. */
@@ -190,7 +197,12 @@ export class AgentContext {
   get instructionTokens(): number {
     const summaryOverhead =
       this._summaryLocation === 'user_message' ? this.summaryTokenCount : 0;
-    return this.systemMessageTokens + this.toolSchemaTokens + summaryOverhead;
+    return (
+      this.systemMessageTokens +
+      this.dynamicInstructionTokens +
+      this.toolSchemaTokens +
+      summaryOverhead
+    );
   }
   /** The amount of time that should pass before another consecutive API call */
   streamBuffer?: number;
@@ -570,20 +582,29 @@ export class AgentContext {
 
     if (!stableInstructions && !dynamicInstructions && !hasMidRunSummary) {
       this.systemMessageTokens = 0;
+      this.dynamicInstructionTokens = 0;
       return undefined;
     }
 
-    const usePromptCache = this.hasAnthropicPromptCache();
+    const promptCacheProvider = this.getPromptCacheProvider();
+    const shouldMoveDynamicInstructions =
+      promptCacheProvider != null &&
+      stableInstructions !== '' &&
+      dynamicInstructions !== '';
     const systemMessage = this.buildSystemMessage({
       stableInstructions,
       dynamicInstructions,
-      usePromptCache,
+      promptCacheProvider,
+      shouldMoveDynamicInstructions,
     });
 
     if (this.tokenCounter) {
       this.systemMessageTokens = systemMessage
         ? this.tokenCounter(systemMessage)
         : 0;
+      this.dynamicInstructionTokens = shouldMoveDynamicInstructions
+        ? this.tokenCounter(new HumanMessage(dynamicInstructions))
+        : 0;
     }
 
     return RunnableLambda.from((messages: BaseMessage[]) => {
@@ -597,45 +618,155 @@ export class AgentContext {
         this.summaryText != null &&
         this.summaryText !== '';
 
-      let body: BaseMessage[];
-      if (hasSummaryBody) {
-        const wrappedSummary =
-          '<summary>\n' +
-          (this.summaryText as string) +
-          '\n</summary>\n\n' +
-          'This is your own checkpoint: you wrote it to preserve context after compaction. Pick up where you left off based on the summary above. Do not repeat prior tasks, information or acknowledge this checkpoint message directly.';
-
-        const summaryMsg = usePromptCache
-          ? new HumanMessage({
-            content: [
-              {
-                type: 'text',
-                text: wrappedSummary,
-                cache_control: { type: 'ephemeral' },
-              },
-            ],
-          })
-          : new HumanMessage(wrappedSummary);
-        body = [summaryMsg, ...messages];
-      } else {
-        body = messages;
-      }
+      const bodyWithSummary =
+        hasSummaryBody && promptCacheProvider == null
+          ? [this.buildSummaryHumanMessage(promptCacheProvider), ...messages]
+          : messages;
+      const dynamicTail = this.buildPromptCacheDynamicTail({
+        dynamicInstructions,
+        hasSummaryBody,
+        promptCacheProvider,
+        shouldMoveDynamicInstructions,
+      });
+      let body = this.buildBodyWithPromptCacheDynamicTail(
+        bodyWithSummary,
+        dynamicTail,
+        promptCacheProvider
+      );
 
-      if (usePromptCache && body.length >= 2) {
+      if (
+        promptCacheProvider != null &&
+        dynamicTail.length === 0 &&
+        body.length >= 2
+      ) {
         body = addCacheControl(body);
       }
       return [...prefix, ...body];
     }).withConfig({ runName: 'prompt' });
   }
 
-  private hasAnthropicPromptCache(): boolean {
-    if (this.provider !== Providers.ANTHROPIC) {
-      return false;
+  private buildSummaryHumanMessage(
+    promptCacheProvider: PromptCacheProvider | undefined
+  ): HumanMessage {
+    const wrappedSummary =
+      '<summary>\n' +
+      (this.summaryText as string) +
+      '\n</summary>\n\n' +
+      'This is your own checkpoint: you wrote it to preserve context after compaction. Pick up where you left off based on the summary above. Do not repeat prior tasks, information or acknowledge this checkpoint message directly.';
+
+    if (promptCacheProvider !== Providers.ANTHROPIC) {
+      return new HumanMessage(wrappedSummary);
     }
-    const anthropicOptions = this.clientOptions as
-      | t.AnthropicClientOptions
-      | undefined;
-    return anthropicOptions?.promptCache === true;
+
+    return new HumanMessage({
+      content: [
+        {
+          type: 'text',
+          text: wrappedSummary,
+          cache_control: { type: 'ephemeral' },
+        },
+      ],
+    });
+  }
+
+  private buildPromptCacheDynamicTail({
+    dynamicInstructions,
+    hasSummaryBody,
+    promptCacheProvider,
+    shouldMoveDynamicInstructions,
+  }: {
+    dynamicInstructions: string;
+    hasSummaryBody: boolean;
+    promptCacheProvider: PromptCacheProvider | undefined;
+    shouldMoveDynamicInstructions: boolean;
+  }): BaseMessage[] {
+    if (promptCacheProvider == null) {
+      return [];
+    }
+
+    const dynamicTail = shouldMoveDynamicInstructions
+      ? [new HumanMessage(dynamicInstructions)]
+      : [];
+
+    if (!hasSummaryBody) {
+      return dynamicTail;
+    }
+
+    return [...dynamicTail, this.buildSummaryHumanMessage(undefined)];
+  }
+
+  private buildBodyWithPromptCacheDynamicTail(
+    messages: BaseMessage[],
+    tail: BaseMessage[],
+    promptCacheProvider: PromptCacheProvider | undefined
+  ): BaseMessage[] {
+    if (tail.length === 0) {
+      return messages;
+    }
+
+    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.length;
+  }
+
+  private addStablePromptCacheMarkers(messages: BaseMessage[]): BaseMessage[] {
+    if (messages.length <= 1) {
+      return messages;
+    }
+
+    return [
+      messages[0],
+      ...addCacheControlToStablePrefixMessages(messages.slice(1), 2),
+    ];
+  }
+
+  private getPromptCacheProvider(): PromptCacheProvider | undefined {
+    if (this.provider === Providers.ANTHROPIC) {
+      const anthropicOptions = this.clientOptions as
+        | t.AnthropicClientOptions
+        | undefined;
+      return anthropicOptions?.promptCache === true
+        ? Providers.ANTHROPIC
+        : undefined;
+    }
+
+    if (this.provider === Providers.OPENROUTER) {
+      const openRouterOptions = this.clientOptions as
+        | t.ProviderOptionsMap[Providers.OPENROUTER]
+        | undefined;
+      return openRouterOptions?.promptCache === true
+        ? Providers.OPENROUTER
+        : undefined;
+    }
+
+    return undefined;
   }
 
   private hasBedrockPromptCache(): boolean {
@@ -651,17 +782,19 @@ export class AgentContext {
   private buildSystemMessage({
     stableInstructions,
     dynamicInstructions,
-    usePromptCache,
+    promptCacheProvider,
+    shouldMoveDynamicInstructions,
   }: {
     stableInstructions: string;
     dynamicInstructions: string;
-    usePromptCache: boolean;
+    promptCacheProvider: PromptCacheProvider | undefined;
+    shouldMoveDynamicInstructions: boolean;
   }): SystemMessage | undefined {
     if (!stableInstructions && !dynamicInstructions) {
       return undefined;
     }
 
-    if (usePromptCache) {
+    if (promptCacheProvider === Providers.ANTHROPIC) {
       const content: AgentSystemContentBlock[] = [];
       if (stableInstructions) {
         content.push({
@@ -670,12 +803,28 @@ 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) {
+      return new SystemMessage(dynamicInstructions);
+    }
+
+    if (promptCacheProvider === Providers.OPENROUTER) {
+      return new SystemMessage({
+        content: [
+          {
+            type: 'text',
+            text: stableInstructions,
+            cache_control: { type: 'ephemeral' },
+          },
+        ],
+      } as BaseMessageFields);
+    }
+
     if (this.hasBedrockPromptCache() && stableInstructions) {
       const content: AgentSystemContentBlock[] = [
         { type: 'text', text: stableInstructions },
@@ -699,6 +848,7 @@ export class AgentContext {
    */
   reset(): void {
     this.systemMessageTokens = 0;
+    this.dynamicInstructionTokens = 0;
     this.toolSchemaTokens = 0;
     this.cachedSystemRunnable = undefined;
     this.systemRunnableStale = true;
@@ -1054,6 +1204,7 @@ export class AgentContext {
       maxContextTokens,
       instructionTokens: this.instructionTokens,
       systemMessageTokens: this.systemMessageTokens,
+      dynamicInstructionTokens: this.dynamicInstructionTokens,
       toolSchemaTokens: this.toolSchemaTokens,
       summaryTokens: this.summaryTokenCount,
       toolCount,
@@ -1072,7 +1223,7 @@ export class AgentContext {
     const lines = [
       'Token budget breakdown:',
       `  maxContextTokens:    ${b.maxContextTokens}`,
-      `  instructionTokens:   ${b.instructionTokens} (system: ${b.systemMessageTokens}, tools: ${b.toolSchemaTokens} [${b.toolCount} tools])`,
+      `  instructionTokens:   ${b.instructionTokens} (system: ${b.systemMessageTokens}, dynamic: ${b.dynamicInstructionTokens}, tools: ${b.toolSchemaTokens} [${b.toolCount} tools])`,
       `  summaryTokens:       ${b.summaryTokens}`,
       `  messageTokens:       ${b.messageTokens} (${b.messageCount} messages)`,
       `  availableForMessages: ${b.availableForMessages}`,

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