illuma-agents 1.0.36 → 1.0.38

package/src/messages/cache.test.ts

@@ -835,6 +835,265 @@ describe('Multi-agent provider interoperability', () => {
   });
 });
 
+describe('Immutability - addCacheControl does not mutate original messages', () => {
+  it('should not mutate original messages when adding cache control to string content', () => {
+    const originalMessages: TestMsg[] = [
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi there' },
+      { role: 'user', content: 'How are you?' },
+    ];
+
+    const originalFirstContent = originalMessages[0].content;
+    const originalThirdContent = originalMessages[2].content;
+
+    const result = addCacheControl(originalMessages as never);
+
+    expect(originalMessages[0].content).toBe(originalFirstContent);
+    expect(originalMessages[2].content).toBe(originalThirdContent);
+    expect(typeof originalMessages[0].content).toBe('string');
+    expect(typeof originalMessages[2].content).toBe('string');
+
+    expect(Array.isArray(result[0].content)).toBe(true);
+    expect(Array.isArray(result[2].content)).toBe(true);
+  });
+
+  it('should not mutate original messages when adding cache control to array content', () => {
+    const originalMessages: TestMsg[] = [
+      {
+        role: 'user',
+        content: [{ type: ContentTypes.TEXT, text: 'Hello' }],
+      },
+      { role: 'assistant', content: 'Hi there' },
+      {
+        role: 'user',
+        content: [{ type: ContentTypes.TEXT, text: 'How are you?' }],
+      },
+    ];
+
+    const originalFirstBlock = {
+      ...(originalMessages[0].content as MessageContentComplex[])[0],
+    };
+    const originalThirdBlock = {
+      ...(originalMessages[2].content as MessageContentComplex[])[0],
+    };
+
+    const result = addCacheControl(originalMessages as never);
+
+    const firstContent = originalMessages[0].content as MessageContentComplex[];
+    const thirdContent = originalMessages[2].content as MessageContentComplex[];
+
+    expect('cache_control' in firstContent[0]).toBe(false);
+    expect('cache_control' in thirdContent[0]).toBe(false);
+    expect(firstContent[0]).toEqual(originalFirstBlock);
+    expect(thirdContent[0]).toEqual(originalThirdBlock);
+
+    const resultFirstContent = result[0].content as MessageContentComplex[];
+    const resultThirdContent = result[2].content as MessageContentComplex[];
+    expect('cache_control' in resultFirstContent[0]).toBe(true);
+    expect('cache_control' in resultThirdContent[0]).toBe(true);
+  });
+
+  it('should not mutate original messages when stripping existing cache control', () => {
+    const originalMessages: TestMsg[] = [
+      {
+        role: 'user',
+        content: [
+          {
+            type: ContentTypes.TEXT,
+            text: 'Hello',
+            cache_control: { type: 'ephemeral' },
+          } as MessageContentComplex,
+        ],
+      },
+      { role: 'assistant', content: 'Hi there' },
+      {
+        role: 'user',
+        content: [{ type: ContentTypes.TEXT, text: 'How are you?' }],
+      },
+    ];
+
+    const originalFirstBlock = (
+      originalMessages[0].content as MessageContentComplex[]
+    )[0];
+
+    addCacheControl(originalMessages as never);
+
+    expect('cache_control' in originalFirstBlock).toBe(true);
+  });
+});
+
+describe('Immutability - addBedrockCacheControl does not mutate original messages', () => {
+  it('should not mutate original messages when adding cache points to string content', () => {
+    const originalMessages: TestMsg[] = [
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi there' },
+    ];
+
+    const originalFirstContent = originalMessages[0].content;
+    const originalSecondContent = originalMessages[1].content;
+
+    const result = addBedrockCacheControl(originalMessages);
+
+    expect(originalMessages[0].content).toBe(originalFirstContent);
+    expect(originalMessages[1].content).toBe(originalSecondContent);
+    expect(typeof originalMessages[0].content).toBe('string');
+    expect(typeof originalMessages[1].content).toBe('string');
+
+    expect(Array.isArray(result[0].content)).toBe(true);
+    expect(Array.isArray(result[1].content)).toBe(true);
+  });
+
+  it('should not mutate original messages when adding cache points to array content', () => {
+    const originalMessages: TestMsg[] = [
+      {
+        role: 'user',
+        content: [{ type: ContentTypes.TEXT, text: 'Hello' }],
+      },
+      {
+        role: 'assistant',
+        content: [{ type: ContentTypes.TEXT, text: 'Hi there' }],
+      },
+    ];
+
+    const originalFirstContentLength = (
+      originalMessages[0].content as MessageContentComplex[]
+    ).length;
+    const originalSecondContentLength = (
+      originalMessages[1].content as MessageContentComplex[]
+    ).length;
+
+    const result = addBedrockCacheControl(originalMessages);
+
+    const firstContent = originalMessages[0].content as MessageContentComplex[];
+    const secondContent = originalMessages[1]
+      .content as MessageContentComplex[];
+
+    expect(firstContent.length).toBe(originalFirstContentLength);
+    expect(secondContent.length).toBe(originalSecondContentLength);
+    expect(firstContent.some((b) => 'cachePoint' in b)).toBe(false);
+    expect(secondContent.some((b) => 'cachePoint' in b)).toBe(false);
+
+    const resultFirstContent = result[0].content as MessageContentComplex[];
+    const resultSecondContent = result[1].content as MessageContentComplex[];
+    expect(resultFirstContent.length).toBe(originalFirstContentLength + 1);
+    expect(resultSecondContent.length).toBe(originalSecondContentLength + 1);
+    expect(resultFirstContent.some((b) => 'cachePoint' in b)).toBe(true);
+    expect(resultSecondContent.some((b) => 'cachePoint' in b)).toBe(true);
+  });
+
+  it('should not mutate original messages when stripping existing cache control', () => {
+    const originalMessages: TestMsg[] = [
+      {
+        role: 'user',
+        content: [
+          {
+            type: ContentTypes.TEXT,
+            text: 'Hello',
+            cache_control: { type: 'ephemeral' },
+          } as MessageContentComplex,
+        ],
+      },
+      {
+        role: 'assistant',
+        content: [
+          { type: ContentTypes.TEXT, text: 'Hi there' },
+          { cachePoint: { type: 'default' } },
+        ],
+      },
+    ];
+
+    const originalFirstBlock = (
+      originalMessages[0].content as MessageContentComplex[]
+    )[0];
+    const originalSecondContentLength = (
+      originalMessages[1].content as MessageContentComplex[]
+    ).length;
+
+    addBedrockCacheControl(originalMessages);
+
+    expect('cache_control' in originalFirstBlock).toBe(true);
+    expect(
+      (originalMessages[1].content as MessageContentComplex[]).length
+    ).toBe(originalSecondContentLength);
+  });
+
+  it('should allow different providers to process same messages without cross-contamination', () => {
+    const sharedMessages: TestMsg[] = [
+      {
+        role: 'user',
+        content: [{ type: ContentTypes.TEXT, text: 'Shared message 1' }],
+      },
+      {
+        role: 'assistant',
+        content: [{ type: ContentTypes.TEXT, text: 'Shared response 1' }],
+      },
+    ];
+
+    const bedrockResult = addBedrockCacheControl(sharedMessages);
+
+    const anthropicResult = addCacheControl(sharedMessages as never);
+
+    const originalFirstContent = sharedMessages[0]
+      .content as MessageContentComplex[];
+    expect(originalFirstContent.some((b) => 'cachePoint' in b)).toBe(false);
+    expect('cache_control' in originalFirstContent[0]).toBe(false);
+
+    const bedrockFirstContent = bedrockResult[0]
+      .content as MessageContentComplex[];
+    expect(bedrockFirstContent.some((b) => 'cachePoint' in b)).toBe(true);
+    expect('cache_control' in bedrockFirstContent[0]).toBe(false);
+
+    const anthropicFirstContent = anthropicResult[0]
+      .content as MessageContentComplex[];
+    expect(anthropicFirstContent.some((b) => 'cachePoint' in b)).toBe(false);
+    expect('cache_control' in anthropicFirstContent[0]).toBe(true);
+  });
+
+  it('should keep lc_kwargs.content in sync with content for LangChain messages', () => {
+    type LangChainLikeMsg = TestMsg & {
+      lc_kwargs?: { content?: MessageContentComplex[] };
+    };
+
+    const messagesWithLcKwargs: LangChainLikeMsg[] = [
+      {
+        role: 'user',
+        content: [{ type: ContentTypes.TEXT, text: 'User message' }],
+        lc_kwargs: {
+          content: [{ type: ContentTypes.TEXT, text: 'User message' }],
+        },
+      },
+      {
+        role: 'assistant',
+        content: [{ type: ContentTypes.TEXT, text: 'Assistant response' }],
+        lc_kwargs: {
+          content: [{ type: ContentTypes.TEXT, text: 'Assistant response' }],
+        },
+      },
+    ];
+
+    const bedrockResult = addBedrockCacheControl(messagesWithLcKwargs);
+
+    const resultFirst = bedrockResult[0] as LangChainLikeMsg;
+    const resultSecond = bedrockResult[1] as LangChainLikeMsg;
+
+    expect(resultFirst.content).toEqual(resultFirst.lc_kwargs?.content);
+    expect(resultSecond.content).toEqual(resultSecond.lc_kwargs?.content);
+
+    const firstContent = resultFirst.content as MessageContentComplex[];
+    const firstLcContent = resultFirst.lc_kwargs
+      ?.content as MessageContentComplex[];
+    expect(firstContent.some((b) => 'cachePoint' in b)).toBe(true);
+    expect(firstLcContent.some((b) => 'cachePoint' in b)).toBe(true);
+
+    const originalFirst = messagesWithLcKwargs[0];
+    const originalContent = originalFirst.content as MessageContentComplex[];
+    const originalLcContent = originalFirst.lc_kwargs
+      ?.content as MessageContentComplex[];
+    expect(originalContent.some((b) => 'cachePoint' in b)).toBe(false);
+    expect(originalLcContent.some((b) => 'cachePoint' in b)).toBe(false);
+  });
+});
+
 describe('Multi-turn cache cleanup', () => {
   it('strips stale Bedrock cache points from previous turns before applying new ones', () => {
     const messages: TestMsg[] = [

package/src/messages/cache.ts

@@ -1,4 +1,11 @@
-import { BaseMessage, MessageContentComplex } from '@langchain/core/messages';
+import {
+  BaseMessage,
+  MessageContentComplex,
+  AIMessage,
+  HumanMessage,
+  SystemMessage,
+  ToolMessage,
+} from '@langchain/core/messages';
 import type { AnthropicMessage } from '@/types/messages';
 import type Anthropic from '@anthropic-ai/sdk';
 import { ContentTypes } from '@/common/enum';
@@ -18,6 +25,102 @@ const debugCache = (message: string, data?: unknown): void => {
   }
 };
 
+/**
+ * Deep clones a message's content to prevent mutation of the original.
+ */
+function deepCloneContent<T extends string | MessageContentComplex[]>(
+  content: T
+): T {
+  if (typeof content === 'string') {
+    return content;
+  }
+  if (Array.isArray(content)) {
+    return content.map((block) => ({ ...block })) as T;
+  }
+  return content;
+}
+
+/**
+ * Simple shallow clone with deep-cloned content.
+ * Used for stripping cache control where we don't need proper LangChain instances.
+ */
+function _shallowCloneMessage<T extends MessageWithContent>(message: T): T {
+  const cloned = {
+    ...message,
+    content: deepCloneContent(message.content ?? ''),
+  } as T;
+  const lcKwargs = (cloned as Record<string, unknown>).lc_kwargs as
+    | Record<string, unknown>
+    | undefined;
+  if (lcKwargs != null) {
+    (cloned as Record<string, unknown>).lc_kwargs = {
+      ...lcKwargs,
+      content: cloned.content,
+    };
+  }
+  return cloned;
+}
+
+/**
+ * Creates a new LangChain message instance with the given content.
+ * Required when adding cache points to ensure proper serialization.
+ */
+function _createNewMessage<T extends MessageWithContent>(
+  message: T,
+  content: MessageContentComplex[]
+): T {
+  if ('getType' in message && typeof message.getType === 'function') {
+    const baseMsg = message as unknown as BaseMessage;
+    const msgType = baseMsg.getType();
+
+    const baseFields = {
+      content,
+      name: baseMsg.name,
+      additional_kwargs: { ...baseMsg.additional_kwargs },
+      response_metadata: { ...baseMsg.response_metadata },
+      id: baseMsg.id,
+    };
+
+    switch (msgType) {
+    case 'human':
+      return new HumanMessage(baseFields) as unknown as T;
+    case 'ai': {
+      const aiMsg = baseMsg as AIMessage;
+      return new AIMessage({
+        ...baseFields,
+        tool_calls: aiMsg.tool_calls ? [...aiMsg.tool_calls] : [],
+        invalid_tool_calls: aiMsg.invalid_tool_calls
+          ? [...aiMsg.invalid_tool_calls]
+          : [],
+        usage_metadata: aiMsg.usage_metadata,
+      }) as unknown as T;
+    }
+    case 'system':
+      return new SystemMessage(baseFields) as unknown as T;
+    case 'tool': {
+      const toolMsg = baseMsg as ToolMessage;
+      return new ToolMessage({
+        ...baseFields,
+        tool_call_id: toolMsg.tool_call_id,
+        status: toolMsg.status,
+        artifact: toolMsg.artifact,
+      }) as unknown as T;
+    }
+    default:
+      break;
+    }
+  }
+
+  const cloned = { ...message, content } as T;
+  const lcKwargs = (cloned as Record<string, unknown>).lc_kwargs as
+    | Record<string, unknown>
+    | undefined;
+  if (lcKwargs != null) {
+    (cloned as Record<string, unknown>).lc_kwargs = { ...lcKwargs, content };
+  }
+  return cloned;
+}
+
 /**
  * Anthropic API: Adds cache control to the appropriate user messages in the payload.
  * Strips ALL existing cache control (both Anthropic and Bedrock formats) from all messages,

package/src/messages/core.ts

@@ -41,7 +41,7 @@ User: ${userMessage[1]}
 const _allowedTypes = ['image_url', 'text', 'tool_use', 'tool_result'];
 const allowedTypesByProvider: Record<string, string[]> = {
   default: _allowedTypes,
-  [Providers.ANTHROPIC]: [..._allowedTypes, 'thinking'],
+  [Providers.ANTHROPIC]: [..._allowedTypes, 'thinking', 'redacted_thinking'],
   [Providers.BEDROCK]: [..._allowedTypes, 'reasoning_content'],
   [Providers.OPENAI]: _allowedTypes,
 };

package/src/messages/tools.ts

@@ -47,7 +47,7 @@ export function extractToolDiscoveries(messages: BaseMessage[]): string[] {
     // Use getType() instead of instanceof to avoid module mismatch issues
     if (msg.getType() !== MessageTypes.TOOL) continue;
     const toolMsg = msg as ToolMessage;
-    if (toolMsg.name !== Constants.TOOL_SEARCH_REGEX) continue;
+    if (toolMsg.name !== Constants.TOOL_SEARCH) continue;
     if (!toolCallIds.has(toolMsg.tool_call_id)) continue;
 
     // This is a tool search result from the current turn
@@ -95,7 +95,7 @@ export function hasToolSearchInCurrentTurn(messages: BaseMessage[]): boolean {
     const msg = messages[i];
     if (
       msg.getType() === MessageTypes.TOOL &&
-      (msg as ToolMessage).name === Constants.TOOL_SEARCH_REGEX &&
+      (msg as ToolMessage).name === Constants.TOOL_SEARCH &&
       toolCallIds.has((msg as ToolMessage).tool_call_id)
     ) {
       return true;

package/src/scripts/caching.ts

@@ -1,7 +1,11 @@
 // src/scripts/test-prompt-caching.ts
 import { config } from 'dotenv';
 config();
-import { HumanMessage, SystemMessage, BaseMessage } from '@langchain/core/messages';
+import {
+  HumanMessage,
+  SystemMessage,
+  BaseMessage,
+} from '@langchain/core/messages';
 import type { UsageMetadata } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
@@ -11,7 +15,7 @@ import { getLLMConfig } from '@/utils/llmConfig';
 import { getArgs } from '@/scripts/args';
 import { Run } from '@/run';
 
-const CACHED_TEXT = `Ahoy there, me hearties! This be a grand tale o' the mighty prompt cachin' treasure map, a secret technique used by the wise Anthropic seafarers to stash away vast hordes o' text booty on their mystical servers! Arrr, 'tis a pirate's dream indeed - no need to haul the same heavy chest o' gold doubloons across the vast digital ocean with every message! When ye mark yer precious cargo with the secret flag 'cache_control: { type: \"ephemeral\" }', the text be safely buried on their distant shores, ready for plunderin' again without the weight slowin' down yer ship! The wise pirates at Anthropic introduced this magical scroll in the summer o' 2024, markin' it with the mysterious insignia 'anthropic-beta: prompt-caching-2024-07-31' that must be flown high on yer vessel's headers. This crafty script be testin' the waters of this new treasure map system, sendin' out three separate voyages across the AI seas: first to bury the treasure, second to dig it up again without payin' the full toll, and third to see if the map still leads to gold after the sands o' time have shifted (about thirty seconds o' waitin', which be an eternity for an impatient buccaneer!). The great advantage for a scurvy pirate captain is clear as Caribbean waters - ye can load up yer vessel with all manner o' reference scrolls, ancient tomes, and navigational charts without weighin' down each and every message ye send to port! This be savin' ye countless tokens, which as any seafarin' AI wrangler knows, be as precious as Spanish gold. The cached text could contain the full history o' the Seven Seas, detailed maps o' every port from Tortuga to Singapore, or the complete collection o' pirate shanties ever sung by drunken sailors under the light o' the silvery moon. When properly implemented, this mighty cachin' system keeps all that knowledge ready at hand without the Claude kraken needin' to process it anew with each passin' breeze. By Blackbeard's beard, 'tis a revolution in how we manage our conversational ships! The script be employin' the finest LangChain riggin' and custom-carved event handlers to properly track the treasure as it flows back and forth. If ye be successful in yer implementation, ye should witness the miracle o' significantly reduced token counts in yer usage metrics, faster responses from the AI oracle, and the ability to maintain vast knowledge without payin' the full price each time! So hoist the Jolly Roger, load yer pistols with API keys, and set sail on the grand adventure o' prompt cachin'! May the winds o' efficient token usage fill yer sails, and may ye never have to pay full price for passin' the same mammoth context to Claude again! Remember, a clever pirate only pays for their tokens once, then lets the cache do the heavy liftin'! YARRR! This file also contains the secrets of the legendary Pirate Code, passed down through generations of seafarers since the Golden Age of Piracy. It includes detailed accounts of famous pirate captains like Blackbeard, Calico Jack, Anne Bonny, and Mary Read, along with their most profitable plundering routes and techniques for capturing merchant vessels. The text chronicles the exact locations of at least seventeen buried treasures across the Caribbean, complete with riddles and map coordinates that only a true pirate could decipher. There are sections dedicated to ship maintenance, including how to properly seal a leaking hull during battle and the best methods for keeping your cannons in prime firing condition even in humid tropical conditions. The document contains an extensive glossary of pirate terminology, from 'avast' to 'Yellow Jack,' ensuring any landlubber can speak like a seasoned salt with enough study. There's a comprehensive guide to navigating by the stars without modern instruments, perfect for when your GPS fails in the middle of a daring escape. The cache also includes detailed recipes for grog, hardtack that won't break your teeth, and how to keep citrus fruits fresh to prevent scurvy during long voyages. The legendary Black Spot ritual is described in terrifying detail, along with other pirate superstitions and their origins in maritime folklore. A section on pirate governance explains the democratic nature of most pirate ships, how booty was divided fairly, and how captains were elected and deposed when necessary. The file even contains sheet music for dozens of sea shanties, with notes on when each should be sung for maximum crew morale during different sailing conditions. All of this knowledge is wrapped in colorful pirate dialect that would make any AI assistant respond with appropriate 'arghs' and 'avasts' when properly prompted!`
+const CACHED_TEXT = `Ahoy there, me hearties! This be a grand tale o' the mighty prompt cachin' treasure map, a secret technique used by the wise Anthropic seafarers to stash away vast hordes o' text booty on their mystical servers! Arrr, 'tis a pirate's dream indeed - no need to haul the same heavy chest o' gold doubloons across the vast digital ocean with every message! When ye mark yer precious cargo with the secret flag 'cache_control: { type: \"ephemeral\" }', the text be safely buried on their distant shores, ready for plunderin' again without the weight slowin' down yer ship! The wise pirates at Anthropic introduced this magical scroll in the summer o' 2024, markin' it with the mysterious insignia 'anthropic-beta: prompt-caching-2024-07-31' that must be flown high on yer vessel's headers. This crafty script be testin' the waters of this new treasure map system, sendin' out three separate voyages across the AI seas: first to bury the treasure, second to dig it up again without payin' the full toll, and third to see if the map still leads to gold after the sands o' time have shifted (about thirty seconds o' waitin', which be an eternity for an impatient buccaneer!). The great advantage for a scurvy pirate captain is clear as Caribbean waters - ye can load up yer vessel with all manner o' reference scrolls, ancient tomes, and navigational charts without weighin' down each and every message ye send to port! This be savin' ye countless tokens, which as any seafarin' AI wrangler knows, be as precious as Spanish gold. The cached text could contain the full history o' the Seven Seas, detailed maps o' every port from Tortuga to Singapore, or the complete collection o' pirate shanties ever sung by drunken sailors under the light o' the silvery moon. When properly implemented, this mighty cachin' system keeps all that knowledge ready at hand without the Claude kraken needin' to process it anew with each passin' breeze. By Blackbeard's beard, 'tis a revolution in how we manage our conversational ships! The script be employin' the finest LangChain riggin' and custom-carved event handlers to properly track the treasure as it flows back and forth. If ye be successful in yer implementation, ye should witness the miracle o' significantly reduced token counts in yer usage metrics, faster responses from the AI oracle, and the ability to maintain vast knowledge without payin' the full price each time! So hoist the Jolly Roger, load yer pistols with API keys, and set sail on the grand adventure o' prompt cachin'! May the winds o' efficient token usage fill yer sails, and may ye never have to pay full price for passin' the same mammoth context to Claude again! Remember, a clever pirate only pays for their tokens once, then lets the cache do the heavy liftin'! YARRR! This file also contains the secrets of the legendary Pirate Code, passed down through generations of seafarers since the Golden Age of Piracy. It includes detailed accounts of famous pirate captains like Blackbeard, Calico Jack, Anne Bonny, and Mary Read, along with their most profitable plundering routes and techniques for capturing merchant vessels. The text chronicles the exact locations of at least seventeen buried treasures across the Caribbean, complete with riddles and map coordinates that only a true pirate could decipher. There are sections dedicated to ship maintenance, including how to properly seal a leaking hull during battle and the best methods for keeping your cannons in prime firing condition even in humid tropical conditions. The document contains an extensive glossary of pirate terminology, from 'avast' to 'Yellow Jack,' ensuring any landlubber can speak like a seasoned salt with enough study. There's a comprehensive guide to navigating by the stars without modern instruments, perfect for when your GPS fails in the middle of a daring escape. The cache also includes detailed recipes for grog, hardtack that won't break your teeth, and how to keep citrus fruits fresh to prevent scurvy during long voyages. The legendary Black Spot ritual is described in terrifying detail, along with other pirate superstitions and their origins in maritime folklore. A section on pirate governance explains the democratic nature of most pirate ships, how booty was divided fairly, and how captains were elected and deposed when necessary. The file even contains sheet music for dozens of sea shanties, with notes on when each should be sung for maximum crew morale during different sailing conditions. All of this knowledge is wrapped in colorful pirate dialect that would make any AI assistant respond with appropriate 'arghs' and 'avasts' when properly prompted!`;
 
 const conversationHistory: BaseMessage[] = [];
 let _contentParts: t.MessageContentComplex[] = [];
@@ -23,7 +27,7 @@ async function testPromptCaching(): Promise<void> {
 ${CACHED_TEXT}`;
   const { contentParts, aggregateContent } = createContentAggregator();
   _contentParts = contentParts as t.MessageContentComplex[];
-  
+
   // Set up event handlers
   const customHandlers = {
     [GraphEvents.TOOL_END]: new ToolEndHandler(),
@@ -33,29 +37,33 @@ ${CACHED_TEXT}`;
     [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
     // Additional handlers for tracking usage metrics
     [GraphEvents.ON_RUN_STEP_COMPLETED]: {
-      handle: (event: GraphEvents.ON_RUN_STEP_COMPLETED, data: t.StreamEventData): void => {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData
+      ): void => {
         console.log('====== ON_RUN_STEP_COMPLETED ======');
-        aggregateContent({ event, data: data as unknown as { result: t.ToolEndEvent } });
-      }
+        aggregateContent({
+          event,
+          data: data as unknown as { result: t.ToolEndEvent },
+        });
+      },
     },
   };
 
-  const baseLlmConfig: t.LLMConfig & t.AnthropicClientOptions  = getLLMConfig(Providers.ANTHROPIC);
-  
+  const baseLlmConfig: t.LLMConfig & t.AnthropicClientOptions = getLLMConfig(
+    Providers.ANTHROPIC
+  );
+
   if (baseLlmConfig.provider !== 'anthropic') {
-    console.error('This test requires Anthropic as the LLM provider. Please specify provider=anthropic');
+    console.error(
+      'This test requires Anthropic as the LLM provider. Please specify provider=anthropic'
+    );
     process.exit(1);
   }
-  
+
   const llmConfig = {
     ...baseLlmConfig,
-      clientOptions: {
-        ...baseLlmConfig.clientOptions,
-        defaultHeaders: {
-          ...baseLlmConfig.clientOptions?.defaultHeaders,
-          "anthropic-beta": "prompt-caching-2024-07-31",
-        }
-      }
+    promptCache: true,
   };
 
   const run = await Run.create<t.IState>({
@@ -94,7 +102,7 @@ ${CACHED_TEXT}`;
   console.log('\n\nTest 2: Second request (should use cache)');
   const userMessage2 = `Summarize the key concepts from the context information.`;
   conversationHistory.push(new HumanMessage(userMessage2));
-  
+
   console.log('Running second query to use cache...');
   const secondInputs = { messages: [...conversationHistory] };
   await run.processStream(secondInputs, config);
@@ -121,4 +129,4 @@ testPromptCaching().catch((err) => {
   console.log('Content parts:');
   console.dir(_contentParts, { depth: null });
   process.exit(1);
-});
+});

package/src/scripts/code_exec_files.ts

@@ -1,4 +1,11 @@
-// src/scripts/cli.ts
+// src/scripts/code_exec_files.ts
+/**
+ * Tests automatic session tracking for code execution file persistence.
+ * Files created in one execution are automatically available in subsequent executions
+ * without the LLM needing to track or pass session_id.
+ *
+ * Run with: npm run code_exec_files
+ */
 import { config } from 'dotenv';
 config();
 import { HumanMessage, BaseMessage } from '@langchain/core/messages';
@@ -12,12 +19,39 @@ import {
 } from '@/events';
 import { getLLMConfig } from '@/utils/llmConfig';
 import { getArgs } from '@/scripts/args';
-import { GraphEvents } from '@/common';
+import { Constants, GraphEvents } from '@/common';
 import { Run } from '@/run';
 import { createCodeExecutionTool } from '@/tools/CodeExecutor';
 
 const conversationHistory: BaseMessage[] = [];
 
+/**
+ * Prints session context from the graph for debugging
+ */
+function printSessionContext(run: Run<t.IState>): void {
+  const graph = run.Graph;
+  if (!graph) {
+    console.log('[Session] No graph available');
+    return;
+  }
+
+  const session = graph.sessions.get(Constants.EXECUTE_CODE) as
+    | t.CodeSessionContext
+    | undefined;
+
+  if (!session) {
+    console.log('[Session] No session context stored yet');
+    return;
+  }
+
+  console.log('[Session] Current session context:');
+  console.log(`  - session_id: ${session.session_id}`);
+  console.log(`  - files: ${JSON.stringify(session.files, null, 2)}`);
+  console.log(
+    `  - lastUpdated: ${new Date(session.lastUpdated).toISOString()}`
+  );
+}
+
 async function testCodeExecution(): Promise<void> {
   const { userName, location, provider, currentDate } = await getArgs();
   const { contentParts, aggregateContent } = createContentAggregator();
@@ -72,7 +106,7 @@ async function testCodeExecution(): Promise<void> {
       handle: (
         _event: string,
         data: t.StreamEventData,
-        metadata?: Record<string, unknown>
+        _metadata?: Record<string, unknown>
       ): void => {
         console.log('====== TOOL_START ======');
         console.dir(data, { depth: null });
@@ -96,7 +130,7 @@ async function testCodeExecution(): Promise<void> {
     customHandlers,
   });
 
-  const config: Partial<RunnableConfig> & {
+  const streamConfig: Partial<RunnableConfig> & {
     version: 'v1' | 'v2';
     run_id?: string;
     streamMode: string;
@@ -107,10 +141,12 @@ async function testCodeExecution(): Promise<void> {
     },
     streamMode: 'values',
     version: 'v2' as const,
-    // recursionLimit: 3,
   };
 
-  console.log('Test 1: Create Project Plan');
+  console.log('\n========== Test 1: Create Project Plan ==========\n');
+  console.log(
+    'Creating initial file - this establishes the session context.\n'
+  );
 
   const userMessage1 = `
   Hi ${userName} here. We are testing your file capabilities.
@@ -125,36 +161,43 @@ async function testCodeExecution(): Promise<void> {
   let inputs = {
     messages: conversationHistory,
   };
-  const finalContentParts1 = await run.processStream(inputs, config);
+  await run.processStream(inputs, streamConfig);
   const finalMessages1 = run.getRunMessages();
   if (finalMessages1) {
     conversationHistory.push(...finalMessages1);
   }
-  console.log('\n\n====================\n\n');
+
+  console.log('\n\n========== Session Context After Test 1 ==========\n');
+  printSessionContext(run);
   console.dir(contentParts, { depth: null });
 
-  console.log('Test 2: Edit Project Plan');
+  console.log('\n========== Test 2: Edit Project Plan ==========\n');
+  console.log(
+    'Editing the file from Test 1 - session_id is automatically injected.\n'
+  );
 
   const userMessage2 = `
   Thanks for creating the project plan. Now I'd like you to edit the same plan to:
   
-  1. Add a new section called "Technology Stack" that contains: "The technology stack for this project includes the following technologies" and nothing more.
-  
+  1. Read the existing project_plan.txt file
+  2. Add a new section called "Technology Stack" that contains: "The technology stack for this project includes the following technologies" and nothing more.
+  3. Save this as a new file called "project_plan_v2.txt" (remember files are read-only)
+  4. Print the contents of both files to verify
 `;
 
-  // Make sure to pass the file ID of the previous file you created and explicitly duplicate or rename the file in your code so we can then access it. Also print the contents of the new file to ensure we did what we wanted.`;
-
   conversationHistory.push(new HumanMessage(userMessage2));
 
   inputs = {
     messages: conversationHistory,
   };
-  const finalContentParts2 = await run.processStream(inputs, config);
+  await run.processStream(inputs, streamConfig);
   const finalMessages2 = run.getRunMessages();
   if (finalMessages2) {
     conversationHistory.push(...finalMessages2);
   }
-  console.log('\n\n====================\n\n');
+
+  console.log('\n\n========== Session Context After Test 2 ==========\n');
+  printSessionContext(run);
   console.dir(contentParts, { depth: null });
 
   const { handleLLMEnd, collected } = createMetadataAggregator();