illuma-agents 1.0.11 → 1.0.13

package/dist/types/llm/anthropic/index.d.ts

@@ -21,7 +21,7 @@ export declare class CustomAnthropic extends ChatAnthropicMessages {
     private emitted_usage?;
     top_k: number | undefined;
     constructor(fields?: CustomAnthropicInput);
-    static lc_name(): 'LibreChatAnthropic';
+    static lc_name(): 'IllumaAnthropic';
     /**
      * Get the parameters used to invoke the model
      */

package/dist/types/llm/google/index.d.ts

@@ -12,7 +12,7 @@ export declare class CustomChatGoogleGenerativeAI extends ChatGoogleGenerativeAI
      */
     get _isMultimodalModel(): boolean;
     constructor(fields: GoogleClientOptions);
-    static lc_name(): 'LibreChatGoogleGenerativeAI';
+    static lc_name(): 'IllumaGoogleGenerativeAI';
     /**
      * Helper function to convert Gemini API usage metadata to LangChain format
      * Includes support for cached tokens and tier-based tracking for gemini-3-pro-preview

package/dist/types/llm/openai/index.d.ts

@@ -63,7 +63,7 @@ export declare class AzureChatOpenAI extends OriginalAzureChatOpenAI {
         _lc_stream_delay?: number;
     });
     get exposedClient(): CustomOpenAIClient;
-    static lc_name(): 'LibreChatAzureOpenAI';
+    static lc_name(): 'IllumaAzureOpenAI';
     /**
      * Returns backwards compatible reasoning parameters from constructor params and call options
      * @internal
@@ -75,7 +75,7 @@ export declare class AzureChatOpenAI extends OriginalAzureChatOpenAI {
 }
 export declare class ChatDeepSeek extends OriginalChatDeepSeek {
     get exposedClient(): CustomOpenAIClient;
-    static lc_name(): 'LibreChatDeepSeek';
+    static lc_name(): 'IllumaDeepSeek';
     protected _getClientOptions(options?: OpenAICoreRequestOptions): OpenAICoreRequestOptions;
     _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
 }
@@ -106,7 +106,7 @@ export declare class ChatXAI extends OriginalChatXAI {
         };
         _lc_stream_delay?: number;
     });
-    static lc_name(): 'LibreChatXAI';
+    static lc_name(): 'IllumaXAI';
     get exposedClient(): CustomOpenAIClient;
     protected _getClientOptions(options?: OpenAICoreRequestOptions): OpenAICoreRequestOptions;
     _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;

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

@@ -9,7 +9,7 @@ export interface ChatOpenRouterCallOptions extends ChatOpenAICallOptions {
 }
 export declare class ChatOpenRouter extends ChatOpenAI {
     constructor(_fields: Partial<ChatOpenRouterCallOptions>);
-    static lc_name(): 'LibreChatOpenRouter';
+    static lc_name(): 'IllumaOpenRouter';
     protected _convertOpenAIDeltaToBaseMessageChunk(delta: Record<string, any>, rawResponse: OpenAIClient.ChatCompletionChunk, defaultRole?: 'function' | 'user' | 'system' | 'developer' | 'assistant' | 'tool'): AIMessageChunk | HumanMessageChunk | SystemMessageChunk | FunctionMessageChunk | ToolMessageChunk | ChatMessageChunk;
     _streamResponseChunks2(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
 }

package/dist/types/types/graph.d.ts

@@ -254,4 +254,11 @@ export interface AgentInputs {
      * Maps tool name to LCTool definition.
      */
     toolRegistry?: Map<string, LCTool>;
+    /**
+     * Dynamic context that changes per-request (e.g., current time, user info).
+     * This is injected as a user message rather than system prompt to preserve cache.
+     * Keeping this separate from instructions ensures the system message stays static
+     * and can be cached by Bedrock/Anthropic prompt caching.
+     */
+    dynamicContext?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "illuma-agents",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -15,12 +15,6 @@
   "description": "Illuma AI Agents Library",
   "author": "Varun Muppidi",
   "license": "MIT",
-  "licenses": [
-    {
-      "type": "MIT",
-      "url": "https://github.com/danny-avila/agents/blob/main/LICENSE"
-    }
-  ],
   "packageManager": "npm@10.5.2",
   "engines": {
     "node": ">=14.0.0"

package/src/agents/AgentContext.ts

@@ -39,6 +39,7 @@ export class AgentContext {
       maxContextTokens,
       reasoningKey,
       useLegacyContent,
+      dynamicContext,
     } = agentConfig;
 
     const agentContext = new AgentContext({
@@ -57,6 +58,7 @@ export class AgentContext {
       instructionTokens: 0,
       tokenCounter,
       useLegacyContent,
+      dynamicContext,
     });
 
     if (tokenCounter) {
@@ -120,6 +122,12 @@ export class AgentContext {
   instructions?: string;
   /** Additional instructions for this agent */
   additionalInstructions?: string;
+  /**
+   * Dynamic context that changes per-request (e.g., current time, user info).
+   * This is NOT included in the system message to preserve cache.
+   * Instead, it's injected as a user message at the start of the conversation.
+   */
+  dynamicContext?: string;
   /** Reasoning key for this agent */
   reasoningKey: 'reasoning_content' | 'reasoning' = 'reasoning_content';
   /** Last token for reasoning detection */
@@ -145,6 +153,10 @@ export class AgentContext {
   tokenCalculationPromise?: Promise<void>;
   /** Format content blocks as strings (for legacy compatibility) */
   useLegacyContent: boolean = false;
+  /** Detailed per-tool token breakdown for admin tracking */
+  private toolsDetail: Array<{ name: string; tokens: number }> = [];
+  /** Total tool tokens (sum of all toolsDetail) */
+  private toolTokensTotal: number = 0;
 
   constructor({
     agentId,
@@ -158,6 +170,7 @@ export class AgentContext {
     toolRegistry,
     instructions,
     additionalInstructions,
+    dynamicContext,
     reasoningKey,
     toolEnd,
     instructionTokens,
@@ -174,6 +187,7 @@ export class AgentContext {
     toolRegistry?: t.LCToolRegistry;
     instructions?: string;
     additionalInstructions?: string;
+    dynamicContext?: string;
     reasoningKey?: 'reasoning_content' | 'reasoning';
     toolEnd?: boolean;
     instructionTokens?: number;
@@ -190,6 +204,7 @@ export class AgentContext {
     this.toolRegistry = toolRegistry;
     this.instructions = instructions;
     this.additionalInstructions = additionalInstructions;
+    this.dynamicContext = dynamicContext;
     if (reasoningKey) {
       this.reasoningKey = reasoningKey;
     }
@@ -375,8 +390,6 @@ export class AgentContext {
       const supportsCaching = modelId.includes('claude') || modelId.includes('anthropic') || modelId.includes('nova');
 
       if (bedrockOptions?.promptCache === true && supportsCaching) {
-        // Always log system cache structure
-        console.log(`[Cache] 📝 System | chars=${instructionsString.length} | tokens=${this.systemMessageTokens} | model=${modelId}`);
         
         finalInstructions = {
           content: [
@@ -412,6 +425,8 @@ export class AgentContext {
   reset(): void {
     this.instructionTokens = 0;
     this.systemMessageTokens = 0;
+    this.toolsDetail = [];
+    this.toolTokensTotal = 0;
     this.cachedSystemRunnable = undefined;
     this.systemRunnableStale = true;
     this.lastToken = undefined;
@@ -447,11 +462,14 @@ export class AgentContext {
   /**
    * Calculate tool tokens and add to instruction tokens
    * Note: System message tokens are calculated during systemRunnable creation
+   * Also tracks per-tool token breakdown for admin reporting
    */
   async calculateInstructionTokens(
     tokenCounter: t.TokenCounter
   ): Promise<void> {
     let toolTokens = 0;
+    this.toolsDetail = []; // Reset per-tool breakdown
+    
     if (this.tools && this.tools.length > 0) {
       for (const tool of this.tools) {
         const genericTool = tool as Record<string, unknown>;
@@ -469,17 +487,60 @@ export class AgentContext {
             describedSchema as Parameters<typeof zodToJsonSchema>[0],
             (genericTool.name as string) || ''
           );
-          toolTokens += tokenCounter(
+          const toolName = (genericTool.name as string) || 'unknown';
+          const tokens = tokenCounter(
             new SystemMessage(JSON.stringify(jsonSchema))
           );
+          
+          // Track per-tool breakdown
+          this.toolsDetail.push({ name: toolName, tokens });
+          toolTokens += tokens;
         }
       }
     }
 
+    // Store total tool tokens for breakdown reporting
+    this.toolTokensTotal = toolTokens;
+    
     // Add tool tokens to existing instruction tokens (which may already include system message tokens)
     this.instructionTokens += toolTokens;
   }
 
+  /**
+   * Get a detailed breakdown of context tokens for admin reporting.
+   * This provides visibility into what's consuming the input token budget.
+   * @returns ContextBreakdown object with per-component token counts
+   */
+  getContextBreakdown(): {
+    instructions: number;
+    artifacts: number;
+    tools: number;
+    toolCount: number;
+    toolContext: number;
+    total: number;
+    toolsDetail: Array<{ name: string; tokens: number }>;
+    toolContextDetail: Array<{ name: string; tokens: number }>;
+  } {
+    return {
+      // System message tokens (instructions + additional_instructions)
+      instructions: this.systemMessageTokens,
+      // Artifacts are not currently tracked separately, set to 0
+      artifacts: 0,
+      // Total tool definition tokens
+      tools: this.toolTokensTotal,
+      // Number of tools
+      toolCount: this.toolsDetail.length,
+      // Tool context/usage instructions (currently embedded in system message)
+      toolContext: 0,
+      // Total tracked context tokens
+      total: this.instructionTokens,
+      // Per-tool token breakdown
+      toolsDetail: [...this.toolsDetail],
+      // Tool context detail (currently not tracked separately)
+      toolContextDetail: [],
+    };
+  }
+
   /**
    * Gets the tool registry for deferred tools (for tool search).
    * @param onlyDeferred If true, only returns tools with defer_loading=true

package/src/graphs/Graph.ts

@@ -21,6 +21,7 @@ import {
   ToolMessage,
   SystemMessage,
   AIMessageChunk,
+  HumanMessage,
 } from '@langchain/core/messages';
 import type {
   BaseMessageFields,
@@ -390,6 +391,27 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     return contentPartAgentMap;
   }
 
+  /**
+   * Get the context breakdown from the primary agent for admin token tracking.
+   * Returns detailed token counts for instructions, tools, etc.
+   */
+  getContextBreakdown(): {
+    instructions: number;
+    artifacts: number;
+    tools: number;
+    toolCount: number;
+    toolContext: number;
+    total: number;
+    toolsDetail: Array<{ name: string; tokens: number }>;
+    toolContextDetail: Array<{ name: string; tokens: number }>;
+  } | null {
+    const primaryContext = this.agentContexts.get(this.defaultAgentId);
+    if (!primaryContext) {
+      return null;
+    }
+    return primaryContext.getContextBreakdown();
+  }
+
   /* Graph */
 
   createSystemRunnable({
@@ -624,7 +646,30 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         throw new Error('No config provided');
       }
 
-      const { messages } = state;
+      let { messages } = state;
+
+      // CACHE OPTIMIZATION: Inject dynamicContext as a HumanMessage at the start of conversation
+      // This keeps the system message static (cacheable) while providing dynamic context
+      // (timestamps, user info, tool context) as conversation content instead.
+      // Only inject on the first turn when messages don't already have the context marker.
+      if (
+        agentContext.dynamicContext &&
+        messages.length > 0 &&
+        !messages.some(
+          (m) =>
+            m instanceof HumanMessage &&
+            typeof m.content === 'string' &&
+            m.content.startsWith('[SESSION_CONTEXT]')
+        )
+      ) {
+        const dynamicContextMessage = new HumanMessage({
+          content: `[SESSION_CONTEXT]\n${agentContext.dynamicContext}`,
+        });
+        const ackMessage = new AIMessageChunk({
+          content: 'Understood. I have noted the session context including the current date/time (CST) and will apply it appropriately.',
+        });
+        messages = [dynamicContextMessage, ackMessage, ...messages];
+      }
 
       // Extract tool discoveries from current turn only (similar to formatArtifactPayload pattern)
       const discoveredNames = extractToolDiscoveries(messages);

package/src/llm/anthropic/index.ts

@@ -143,8 +143,8 @@ export class CustomAnthropic extends ChatAnthropicMessages {
     this._lc_stream_delay = fields?._lc_stream_delay ?? 25;
   }
 
-  static lc_name(): 'LibreChatAnthropic' {
-    return 'LibreChatAnthropic';
+  static lc_name(): 'IllumaAnthropic' {
+    return 'IllumaAnthropic';
   }
 
   /**

package/src/llm/bedrock/index.ts

@@ -42,7 +42,7 @@ export class CustomChatBedrockConverse extends ChatBedrockConverse {
   }
 
   static lc_name(): string {
-    return 'LibreChatBedrockConverse';
+    return 'IllumaBedrockConverse';
   }
 
   /**
@@ -92,8 +92,7 @@ export class CustomChatBedrockConverse extends ChatBedrockConverse {
         }
       }
 
-      // Always log cache structure (INFO level for tracking)
-      console.log(`[Cache] 🔧 Tools | Core: [${coreToolNames.join(', ')}] (${coreTools.length}) | MCP: [${mcpToolNames.join(', ')}] (${mcpTools.length})`);
+
 
       // Build tools array with strategic cachePoints:
       // [CoreTool1, CoreTool2, cachePoint] + [MCPTool1, MCPTool2, cachePoint]
@@ -120,7 +119,7 @@ export class CustomChatBedrockConverse extends ChatBedrockConverse {
         cachePointCount++;
       }
       
-      console.log(`[Cache] 📍 Tool cachePoints: ${cachePointCount} | Order: [${coreToolNames.length > 0 ? 'CoreTools→CP' : ''}${mcpToolNames.length > 0 ? '→MCPTools→CP' : ''}]`);
+
       
       params.toolConfig.tools = toolsWithCache;
     }
@@ -176,11 +175,6 @@ export class CustomChatBedrockConverse extends ChatBedrockConverse {
           const outputTokens = (usage.outputTokens as number) ?? 0;
           
           if (cacheRead > 0 || cacheWrite > 0) {
-            // Always log cache results for tracking
-            const cacheStatus = cacheRead > 0 && cacheWrite === 0 ? '✅ HIT' : 
-                               cacheWrite > 0 && cacheRead === 0 ? '📝 WRITE' :
-                               cacheRead > 0 && cacheWrite > 0 ? '🔄 PARTIAL' : '❌ MISS';
-            console.log(`[Cache] ${cacheStatus} | read=${cacheRead} | write=${cacheWrite} | input=${inputTokens} | output=${outputTokens}`);
             
             needsModification = true;
             enhancedUsageMetadata = {

package/src/llm/google/index.ts

@@ -122,8 +122,8 @@ export class CustomChatGoogleGenerativeAI extends ChatGoogleGenerativeAI {
     this.streamUsage = fields.streamUsage ?? this.streamUsage;
   }
 
-  static lc_name(): 'LibreChatGoogleGenerativeAI' {
-    return 'LibreChatGoogleGenerativeAI';
+  static lc_name(): 'IllumaGoogleGenerativeAI' {
+    return 'IllumaGoogleGenerativeAI';
   }
 
   /**

package/src/llm/openai/index.ts

@@ -211,7 +211,7 @@ export class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptions> {
     return this.client;
   }
   static lc_name(): string {
-    return 'LibreChatOpenAI';
+    return 'IllumaOpenAI';
   }
   protected _getClientOptions(
     options?: OpenAICoreRequestOptions
@@ -466,8 +466,8 @@ export class AzureChatOpenAI extends OriginalAzureChatOpenAI {
   public get exposedClient(): CustomOpenAIClient {
     return this.client;
   }
-  static lc_name(): 'LibreChatAzureOpenAI' {
-    return 'LibreChatAzureOpenAI';
+  static lc_name(): 'IllumaAzureOpenAI' {
+    return 'IllumaAzureOpenAI';
   }
   /**
    * Returns backwards compatible reasoning parameters from constructor params and call options
@@ -539,8 +539,8 @@ export class AzureChatOpenAI extends OriginalAzureChatOpenAI {
         ...params.defaultHeaders,
         'User-Agent':
           defaultHeaders['User-Agent'] != null
-            ? `${defaultHeaders['User-Agent']}: librechat-azure-openai-v2`
-            : 'librechat-azure-openai-v2',
+            ? `${defaultHeaders['User-Agent']}: illuma-azure-openai-v2`
+            : 'illuma-azure-openai-v2',
       };
 
       this.client = new CustomAzureOpenAIClient({
@@ -613,8 +613,8 @@ export class ChatDeepSeek extends OriginalChatDeepSeek {
   public get exposedClient(): CustomOpenAIClient {
     return this.client;
   }
-  static lc_name(): 'LibreChatDeepSeek' {
-    return 'LibreChatDeepSeek';
+  static lc_name(): 'IllumaDeepSeek' {
+    return 'IllumaDeepSeek';
   }
   protected _getClientOptions(
     options?: OpenAICoreRequestOptions
@@ -814,8 +814,8 @@ export class ChatXAI extends OriginalChatXAI {
     }
   }
 
-  static lc_name(): 'LibreChatXAI' {
-    return 'LibreChatXAI';
+  static lc_name(): 'IllumaXAI' {
+    return 'IllumaXAI';
   }
 
   public get exposedClient(): CustomOpenAIClient {

package/src/llm/openrouter/index.ts

@@ -44,8 +44,8 @@ export class ChatOpenRouter extends ChatOpenAI {
       },
     });
   }
-  static lc_name(): 'LibreChatOpenRouter' {
-    return 'LibreChatOpenRouter';
+  static lc_name(): 'IllumaOpenRouter' {
+    return 'IllumaOpenRouter';
   }
   protected override _convertOpenAIDeltaToBaseMessageChunk(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/messages/cache.ts

@@ -7,14 +7,10 @@ type MessageWithContent = {
   content?: string | MessageContentComplex[];
 };
 
-/** Always-on logger for cache operations */
-const logCache = (message: string) => {
-  console.log(`[Cache] ${message}`);
-};
-
 /** Debug logger for cache operations - set ILLUMA_DEBUG_CACHE=true to enable */
 const debugCache = (message: string, data?: unknown) => {
   if (process.env.ILLUMA_DEBUG_CACHE === 'true') {
+    // eslint-disable-next-line no-console
     console.log(`[Cache] ${message}`, data !== undefined ? JSON.stringify(data, null, 2) : '');
   }
 };
@@ -266,12 +262,12 @@ export function addBedrockCacheControl<
   }
 
   // Log message summary
-  logCache(`📨 Messages | total=${updatedMessages.length} | ${Object.entries(messageTypes).map(([k,v]) => `${k}:${v}`).join(' ')} | skippedReasoning=${skippedWithReasoning}`);
+  debugCache(`📨 Messages | total=${updatedMessages.length} | ${Object.entries(messageTypes).map(([k,v]) => `${k}:${v}`).join(' ')} | skippedReasoning=${skippedWithReasoning}`);
 
   // If no suitable assistant message found, skip conversation caching
   // (System and Tools caching are still handled separately)
   if (lastAssistantIndex === -1) {
-    logCache('📨 Messages | No suitable assistant message for cachePoint (first turn or all have reasoning)');
+    debugCache('📨 Messages | No suitable assistant message for cachePoint (first turn or all have reasoning)');
     return updatedMessages;
   }
 
@@ -284,7 +280,7 @@ export function addBedrockCacheControl<
       { type: ContentTypes.TEXT, text: content },
       { cachePoint: { type: 'default' } },
     ] as MessageContentComplex[];
-    logCache(`📍 Message cachePoint at index ${lastAssistantIndex} (string, ${content.length} chars)`);
+    debugCache(`📍 Message cachePoint at index ${lastAssistantIndex} (string, ${content.length} chars)`);
     debugCache('addBedrockCacheControl: Added cachePoint to assistant message (string content)', {
       index: lastAssistantIndex,
       contentLength: content.length,
@@ -293,7 +289,7 @@ export function addBedrockCacheControl<
     // Double-check: If this message has reasoning blocks, skip adding cache point entirely
     // This handles edge cases where the initial skip check might have missed it
     if (hasReasoningBlock(assistantMessage)) {
-      logCache(`⚠️ Message cachePoint SKIPPED at index ${lastAssistantIndex} (has reasoning blocks)`);
+      debugCache(`⚠️ Message cachePoint SKIPPED at index ${lastAssistantIndex} (has reasoning blocks)`);
       debugCache('addBedrockCacheControl: Skipping - assistant message has reasoning blocks (safety check)', {
         index: lastAssistantIndex,
       });
@@ -312,7 +308,7 @@ export function addBedrockCacheControl<
             cachePoint: { type: 'default' },
           } as MessageContentComplex);
           inserted = true;
-          logCache(`📍 Message cachePoint at index ${lastAssistantIndex} (array, block ${j}, ${text.length} chars)`);
+          debugCache(`📍 Message cachePoint at index ${lastAssistantIndex} (array, block ${j}, ${text.length} chars)`);
           debugCache('addBedrockCacheControl: Added cachePoint after text block in assistant message', {
             index: lastAssistantIndex,
             textBlockIndex: j,
@@ -326,7 +322,7 @@ export function addBedrockCacheControl<
     // If no text block found, don't append cache point as the message structure is unexpected
     if (!inserted) {
       const contentTypes = assistantMessage.content.map((b) => (b as { type?: string }).type);
-      logCache(`⚠️ Message cachePoint SKIPPED at index ${lastAssistantIndex} (no text block, types: ${contentTypes.join(',')})`);
+      debugCache(`⚠️ Message cachePoint SKIPPED at index ${lastAssistantIndex} (no text block, types: ${contentTypes.join(',')})`);
       debugCache('addBedrockCacheControl: No suitable text block found, skipping cache point', {
         index: lastAssistantIndex,
         contentTypes,

package/src/scripts/programmatic_exec.ts

@@ -94,10 +94,10 @@ async function main(): Promise<void> {
   console.log('==============================================');
   console.log('Demonstrating runtime toolMap injection\n');
 
-  const apiKey = process.env.LIBRECHAT_CODE_API_KEY;
+  const apiKey = process.env.CODE_EXECUTOR_API_KEY;
   if (!apiKey) {
     console.error(
-      'Error: LIBRECHAT_CODE_API_KEY environment variable is not set.'
+      'Error: CODE_EXECUTOR_API_KEY environment variable is not set.'
     );
     console.log('Please set it in your .env file or environment.');
     process.exit(1);

package/src/scripts/tool_search_regex.ts

@@ -66,10 +66,10 @@ async function main(): Promise<void> {
   console.log('================================');
   console.log('Demonstrating runtime tool registry injection\n');
 
-  const apiKey = process.env.LIBRECHAT_CODE_API_KEY;
+  const apiKey = process.env.CODE_EXECUTOR_API_KEY;
   if (!apiKey) {
     console.error(
-      'Error: LIBRECHAT_CODE_API_KEY environment variable is not set.'
+      'Error: CODE_EXECUTOR_API_KEY environment variable is not set.'
     );
     console.log('Please set it in your .env file or environment.');
     process.exit(1);

package/src/tools/__tests__/ProgrammaticToolCalling.integration.test.ts

@@ -25,10 +25,10 @@ describe('ProgrammaticToolCalling - Live API Integration', () => {
   let toolDefinitions: t.LCTool[];
 
   beforeAll(() => {
-    const apiKey = process.env.LIBRECHAT_CODE_API_KEY;
+    const apiKey = process.env.CODE_EXECUTOR_API_KEY;
     if (apiKey == null || apiKey === '') {
       throw new Error(
-        'LIBRECHAT_CODE_API_KEY not set. Required for integration tests.'
+        'CODE_EXECUTOR_API_KEY not set. Required for integration tests.'
       );
     }
 

package/src/tools/__tests__/ToolSearchRegex.integration.test.ts

@@ -17,10 +17,10 @@ describe('ToolSearchRegex - Live API Integration', () => {
   const toolRegistry = createToolSearchToolRegistry();
 
   beforeAll(() => {
-    const apiKey = process.env.LIBRECHAT_CODE_API_KEY;
+    const apiKey = process.env.CODE_EXECUTOR_API_KEY;
     if (apiKey == null || apiKey === '') {
       throw new Error(
-        'LIBRECHAT_CODE_API_KEY not set. Required for integration tests.'
+        'CODE_EXECUTOR_API_KEY not set. Required for integration tests.'
       );
     }
 

package/src/types/graph.ts

@@ -375,4 +375,11 @@ export interface AgentInputs {
    * Maps tool name to LCTool definition.
    */
   toolRegistry?: Map<string, LCTool>;
+  /**
+   * Dynamic context that changes per-request (e.g., current time, user info).
+   * This is injected as a user message rather than system prompt to preserve cache.
+   * Keeping this separate from instructions ensures the system message stays static
+   * and can be cached by Bedrock/Anthropic prompt caching.
+   */
+  dynamicContext?: string;
 }