@librechat/agents 3.1.81 → 3.1.82

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,10 @@ export declare class AgentContext {
      * Only called when content has actually changed.
      */
     private buildSystemRunnable;
-    private hasAnthropicPromptCache;
+    private buildSummaryHumanMessage;
+    private buildOpenRouterDynamicTail;
+    private insertAfterFirstMessage;
+    private getPromptCacheProvider;
     private hasBedrockPromptCache;
     private buildSystemMessage;
     /**

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/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.82",
   "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

@@ -30,6 +30,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 +179,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 +194,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 +579,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 shouldMoveOpenRouterDynamicInstructions =
+      promptCacheProvider === Providers.OPENROUTER &&
+      stableInstructions !== '' &&
+      dynamicInstructions !== '';
     const systemMessage = this.buildSystemMessage({
       stableInstructions,
       dynamicInstructions,
-      usePromptCache,
+      promptCacheProvider,
     });
 
     if (this.tokenCounter) {
       this.systemMessageTokens = systemMessage
         ? this.tokenCounter(systemMessage)
         : 0;
+      this.dynamicInstructionTokens =
+        shouldMoveOpenRouterDynamicInstructions
+          ? this.tokenCounter(new HumanMessage(dynamicInstructions))
+          : 0;
     }
 
     return RunnableLambda.from((messages: BaseMessage[]) => {
@@ -597,45 +615,114 @@ 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 !== Providers.OPENROUTER
+          ? [this.buildSummaryHumanMessage(promptCacheProvider), ...messages]
+          : messages;
+      const dynamicTail = this.buildOpenRouterDynamicTail({
+        dynamicInstructions,
+        hasSummaryBody,
+        promptCacheProvider,
+        shouldMoveOpenRouterDynamicInstructions,
+      });
+      let body = this.insertAfterFirstMessage(bodyWithSummary, dynamicTail);
 
-      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 buildOpenRouterDynamicTail({
+    dynamicInstructions,
+    hasSummaryBody,
+    promptCacheProvider,
+    shouldMoveOpenRouterDynamicInstructions,
+  }: {
+    dynamicInstructions: string;
+    hasSummaryBody: boolean;
+    promptCacheProvider: PromptCacheProvider | undefined;
+    shouldMoveOpenRouterDynamicInstructions: boolean;
+  }): BaseMessage[] {
+    if (promptCacheProvider !== Providers.OPENROUTER) {
+      return [];
+    }
+
+    const dynamicTail = shouldMoveOpenRouterDynamicInstructions
+      ? [new HumanMessage(dynamicInstructions)]
+      : [];
+
+    if (!hasSummaryBody) {
+      return dynamicTail;
+    }
+
+    return [...dynamicTail, this.buildSummaryHumanMessage(promptCacheProvider)];
+  }
+
+  private insertAfterFirstMessage(
+    messages: BaseMessage[],
+    tail: BaseMessage[]
+  ): BaseMessage[] {
+    if (tail.length === 0) {
+      return messages;
+    }
+
+    if (messages.length === 0) {
+      return tail;
+    }
+
+    return [messages[0], ...tail, ...messages.slice(1)];
+  }
+
+  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 +738,17 @@ export class AgentContext {
   private buildSystemMessage({
     stableInstructions,
     dynamicInstructions,
-    usePromptCache,
+    promptCacheProvider,
   }: {
     stableInstructions: string;
     dynamicInstructions: string;
-    usePromptCache: boolean;
+    promptCacheProvider: PromptCacheProvider | undefined;
   }): SystemMessage | undefined {
     if (!stableInstructions && !dynamicInstructions) {
       return undefined;
     }
 
-    if (usePromptCache) {
+    if (promptCacheProvider === Providers.ANTHROPIC) {
       const content: AgentSystemContentBlock[] = [];
       if (stableInstructions) {
         content.push({
@@ -676,6 +763,25 @@ export class AgentContext {
       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 +805,7 @@ export class AgentContext {
    */
   reset(): void {
     this.systemMessageTokens = 0;
+    this.dynamicInstructionTokens = 0;
     this.toolSchemaTokens = 0;
     this.cachedSystemRunnable = undefined;
     this.systemRunnableStale = true;
@@ -1054,6 +1161,7 @@ export class AgentContext {
       maxContextTokens,
       instructionTokens: this.instructionTokens,
       systemMessageTokens: this.systemMessageTokens,
+      dynamicInstructionTokens: this.dynamicInstructionTokens,
       toolSchemaTokens: this.toolSchemaTokens,
       summaryTokens: this.summaryTokenCount,
       toolCount,
@@ -1072,7 +1180,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.test.ts

@@ -198,6 +198,151 @@ describe('AgentContext', () => {
       );
     });
 
+    it('marks stable OpenRouter system text and keeps first user message stable', async () => {
+      const ctx = createBasicContext({
+        agentConfig: {
+          provider: Providers.OPENROUTER,
+          clientOptions: {
+            model: 'anthropic/claude-haiku-4.5',
+            promptCache: true,
+          },
+          instructions: 'Stable instructions',
+          additional_instructions: 'Dynamic instructions',
+        },
+      });
+
+      const result = await ctx.systemRunnable!.invoke([
+        new HumanMessage('Hello'),
+        new HumanMessage('Second'),
+      ]);
+      const content = result[0].content as TestSystemContentBlock[];
+      expect(content).toEqual([
+        {
+          type: 'text',
+          text: 'Stable instructions',
+          cache_control: { type: 'ephemeral' },
+        },
+      ]);
+      expect(result[1]).toBeInstanceOf(HumanMessage);
+      expect(result[1].content).toBe('Hello');
+      expect(result[2].content).toBe('Dynamic instructions');
+      expect(result[3].content).toBe('Second');
+    });
+
+    it('keeps dynamic-only OpenRouter instructions as system text', async () => {
+      const tokenCounter = (msg: { content: unknown }): number => {
+        const content =
+          typeof msg.content === 'string'
+            ? msg.content
+            : JSON.stringify(msg.content);
+        return content.length;
+      };
+      const ctx = createBasicContext({
+        agentConfig: {
+          provider: Providers.OPENROUTER,
+          clientOptions: {
+            model: 'anthropic/claude-haiku-4.5',
+            promptCache: true,
+          },
+          instructions: undefined,
+          additional_instructions: 'Dynamic only',
+        },
+        tokenCounter,
+      });
+
+      ctx.initializeSystemRunnable();
+      const result = await ctx.systemRunnable!.invoke([
+        new HumanMessage('First'),
+        new HumanMessage('Second'),
+      ]);
+      const firstContent = result[1].content as TestSystemContentBlock[];
+      const secondContent = result[2].content as TestSystemContentBlock[];
+
+      expect(result).toHaveLength(3);
+      expect(result[0].content).toBe('Dynamic only');
+      expect(firstContent[0]).toMatchObject({
+        type: 'text',
+        text: 'First',
+        cache_control: { type: 'ephemeral' },
+      });
+      expect(secondContent[0]).toMatchObject({
+        type: 'text',
+        text: 'Second',
+        cache_control: { type: 'ephemeral' },
+      });
+      expect(ctx.systemMessageTokens).toBeGreaterThan(0);
+      expect(ctx.dynamicInstructionTokens).toBe(0);
+      expect(ctx.instructionTokens).toBe(ctx.systemMessageTokens);
+    });
+
+    it('does not cache OpenRouter body messages after dynamic instructions', async () => {
+      const ctx = createBasicContext({
+        agentConfig: {
+          provider: Providers.OPENROUTER,
+          clientOptions: {
+            model: 'google/gemini-2.5-flash',
+            promptCache: true,
+          },
+          instructions: 'Stable instructions',
+          additional_instructions: 'Dynamic instructions',
+        },
+      });
+
+      const result = await ctx.systemRunnable!.invoke([
+        new HumanMessage('First'),
+        new HumanMessage('Second'),
+      ]);
+
+      expect(result[1].content).toBe('First');
+      expect(result[2].content).toBe('Dynamic instructions');
+      expect(result[3].content).toBe('Second');
+    });
+
+    it('adds OpenRouter body cache points when there is no dynamic tail', async () => {
+      const ctx = createBasicContext({
+        agentConfig: {
+          provider: Providers.OPENROUTER,
+          clientOptions: {
+            model: 'anthropic/claude-haiku-4.5',
+            promptCache: true,
+          },
+          instructions: 'Stable instructions',
+        },
+      });
+
+      const result = await ctx.systemRunnable!.invoke([
+        new HumanMessage('First'),
+        new HumanMessage('Second'),
+      ]);
+      const firstContent = result[1].content as TestSystemContentBlock[];
+      const secondContent = result[2].content as TestSystemContentBlock[];
+      expect(firstContent[0]).toHaveProperty('cache_control');
+      expect(secondContent[0]).toHaveProperty('cache_control');
+    });
+
+    it('places OpenRouter user-message summaries after the first stable message', async () => {
+      const ctx = createBasicContext({
+        agentConfig: {
+          provider: Providers.OPENROUTER,
+          clientOptions: {
+            model: 'anthropic/claude-haiku-4.5',
+            promptCache: true,
+          },
+          instructions: 'Stable instructions',
+        },
+      });
+      ctx.setSummary('Rotating summary', 7);
+
+      const result = await ctx.systemRunnable!.invoke([
+        new HumanMessage('First'),
+        new HumanMessage('Second'),
+      ]);
+
+      expect(result[1].content).toBe('First');
+      expect(result[2].content).toContain('Rotating summary');
+      expect(result[3].content).toBe('Second');
+    });
+
     it('preserves the Bedrock system cache point through message cache-control pass', async () => {
       const ctx = createBasicContext({
         agentConfig: {
@@ -557,6 +702,59 @@ describe('AgentContext', () => {
       expect(ctxWithDeferred.toolSchemaTokens).toBe(ctxBase.toolSchemaTokens);
     });
 
+    it('counts OpenRouter dynamic instructions outside the system message', () => {
+      const ctx = createBasicContext({
+        agentConfig: {
+          provider: Providers.OPENROUTER,
+          clientOptions: {
+            model: 'anthropic/claude-haiku-4.5',
+            promptCache: true,
+          },
+          instructions: 'Stable',
+          additional_instructions: 'Dynamic tail',
+        },
+        tokenCounter: mockTokenCounter,
+      });
+
+      ctx.initializeSystemRunnable();
+
+      expect(ctx.systemMessageTokens).toBeGreaterThan(0);
+      expect(ctx.dynamicInstructionTokens).toBeGreaterThan(0);
+      expect(ctx.instructionTokens).toBe(
+        ctx.systemMessageTokens + ctx.dynamicInstructionTokens
+      );
+      expect(ctx.getTokenBudgetBreakdown().dynamicInstructionTokens).toBe(
+        ctx.dynamicInstructionTokens
+      );
+    });
+
+    it('clears OpenRouter dynamic instruction tokens when no prompt remains', () => {
+      const ctx = createBasicContext({
+        agentConfig: {
+          provider: Providers.OPENROUTER,
+          clientOptions: {
+            model: 'anthropic/claude-haiku-4.5',
+            promptCache: true,
+          },
+          instructions: 'Stable instructions',
+        },
+        tokenCounter: mockTokenCounter,
+      });
+
+      ctx.setInitialSummary('Volatile summary', 8);
+      ctx.initializeSystemRunnable();
+      expect(ctx.dynamicInstructionTokens).toBeGreaterThan(0);
+
+      ctx.instructions = undefined;
+      ctx.clearSummary();
+      ctx.initializeSystemRunnable();
+
+      expect(ctx.systemRunnable).toBeUndefined();
+      expect(ctx.systemMessageTokens).toBe(0);
+      expect(ctx.dynamicInstructionTokens).toBe(0);
+      expect(ctx.instructionTokens).toBe(0);
+    });
+
     it('excludes programmatic-only toolDefinitions from toolSchemaTokens', async () => {
       // getEventDrivenToolsForBinding excludes definitions whose
       // allowed_callers omit 'direct'. Accounting must mirror that — a

package/src/graphs/Graph.ts

@@ -62,6 +62,7 @@ import { isThinkingEnabled } from '@/llm/request';
 import { initializeModel } from '@/llm/init';
 import { HandlerRegistry } from '@/events';
 import { ChatOpenAI } from '@/llm/openai';
+import { partitionAndMarkOpenRouterToolCache } from '@/llm/openrouter/toolCache';
 import type { HookRegistry } from '@/hooks';
 
 const { AGENT, TOOLS, SUMMARIZE } = GraphNodeKeys;
@@ -817,6 +818,19 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             rawToolsForBinding,
             makeIsDeferred(agentContext.toolDefinitions)
           ) ?? rawToolsForBinding;
+      } else if (
+        agentContext.provider === Providers.OPENROUTER &&
+        (
+          agentContext.clientOptions as
+            | t.ProviderOptionsMap[Providers.OPENROUTER]
+            | undefined
+        )?.promptCache === true
+      ) {
+        toolsForBinding =
+          partitionAndMarkOpenRouterToolCache(
+            rawToolsForBinding,
+            makeIsDeferred(agentContext.toolDefinitions)
+          ) ?? rawToolsForBinding;
       }
 
       let model =
@@ -1073,6 +1087,16 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         if (bedrockOptions?.promptCache === true) {
           finalMessages = addBedrockCacheControl<BaseMessage>(finalMessages);
         }
+      } else if (agentContext.provider === Providers.OPENROUTER) {
+        const openRouterOptions = agentContext.clientOptions as
+          | t.ProviderOptionsMap[Providers.OPENROUTER]
+          | undefined;
+        if (
+          openRouterOptions?.promptCache === true &&
+          !agentContext.systemRunnable
+        ) {
+          finalMessages = addCacheControl<BaseMessage>(finalMessages);
+        }
       }
 
       if (