illuma-agents 1.0.37 → 1.0.39

package/src/messages/cache.test.ts

@@ -835,6 +835,310 @@ 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);
+  });
+
+  it('should remove lc_kwargs to prevent serialization mismatch for LangChain messages', () => {
+    type LangChainLikeMsg = TestMsg & {
+      lc_kwargs?: { content?: MessageContentComplex[] };
+    };
+
+    const messagesWithLcKwargs: LangChainLikeMsg[] = [
+      {
+        role: 'user',
+        content: [{ type: ContentTypes.TEXT, text: 'First user message' }],
+        lc_kwargs: {
+          content: [{ type: ContentTypes.TEXT, text: 'First user message' }],
+        },
+      },
+      {
+        role: 'assistant',
+        content: [{ type: ContentTypes.TEXT, text: 'Assistant response' }],
+        lc_kwargs: {
+          content: [{ type: ContentTypes.TEXT, text: 'Assistant response' }],
+        },
+      },
+      {
+        role: 'user',
+        content: [{ type: ContentTypes.TEXT, text: 'Second user message' }],
+        lc_kwargs: {
+          content: [{ type: ContentTypes.TEXT, text: 'Second user message' }],
+        },
+      },
+    ];
+
+    const result = addCacheControl(messagesWithLcKwargs as never);
+
+    const resultFirst = result[0] as LangChainLikeMsg;
+    const resultThird = result[2] as LangChainLikeMsg;
+
+    expect(resultFirst.lc_kwargs).toBeUndefined();
+    expect(resultThird.lc_kwargs).toBeUndefined();
+
+    const firstContent = resultFirst.content as MessageContentComplex[];
+    expect('cache_control' in firstContent[0]).toBe(true);
+
+    const originalFirst = messagesWithLcKwargs[0];
+    const originalContent = originalFirst.content as MessageContentComplex[];
+    const originalLcContent = originalFirst.lc_kwargs
+      ?.content as MessageContentComplex[];
+    expect('cache_control' in originalContent[0]).toBe(false);
+    expect('cache_control' in originalLcContent[0]).toBe(false);
+  });
+});
+
+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 remove lc_kwargs to prevent serialization mismatch 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.lc_kwargs).toBeUndefined();
+    expect(resultSecond.lc_kwargs).toBeUndefined();
+
+    const firstContent = resultFirst.content as MessageContentComplex[];
+    expect(firstContent.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

@@ -18,13 +18,121 @@ 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;
+}
+
+/**
+ * Clones a message with deep-cloned content, explicitly excluding LangChain
+ * serialization metadata to prevent coercion issues.
+ * Keeps lc_kwargs in sync with content to prevent LangChain serialization issues.
+ */
+function cloneMessage<T extends MessageWithContent>(
+  message: T,
+  content: string | MessageContentComplex[]
+): T {
+  const {
+    lc_kwargs: _lc_kwargs,
+    lc_serializable: _lc_serializable,
+    lc_namespace: _lc_namespace,
+    ...rest
+  } = message as T & {
+    lc_kwargs?: unknown;
+    lc_serializable?: unknown;
+    lc_namespace?: unknown;
+  };
+
+  const cloned = { ...rest, content } as T;
+
+  // Sync lc_kwargs.content with the new content to prevent LangChain coercion issues
+  const lcKwargs = (message as Record<string, unknown>).lc_kwargs as
+    | Record<string, unknown>
+    | undefined;
+  if (lcKwargs != null) {
+    (cloned as Record<string, unknown>).lc_kwargs = {
+      ...lcKwargs,
+      content: content,
+    };
+  }
+
+  // LangChain messages don't have a direct 'role' property - derive it from getType()
+  if (
+    'getType' in message &&
+    typeof message.getType === 'function' &&
+    !('role' in cloned)
+  ) {
+    const msgType = (message as unknown as BaseMessage).getType();
+    const roleMap: Record<string, string> = {
+      human: 'user',
+      ai: 'assistant',
+      system: 'system',
+      tool: 'tool',
+    };
+    (cloned as Record<string, unknown>).role = roleMap[msgType] || msgType;
+  }
+
+  return cloned;
+}
+
+/**
+ * Checks if a content block is a cache point
+ */
+function isCachePoint(block: MessageContentComplex): boolean {
+  return 'cachePoint' in block && !('type' in block);
+}
+
+/**
+ * Checks if a message's content needs cache control stripping.
+ * Returns true if content has cachePoint blocks or cache_control fields.
+ */
+function needsCacheStripping(content: MessageContentComplex[]): boolean {
+  for (let i = 0; i < content.length; i++) {
+    const block = content[i];
+    if (isCachePoint(block)) return true;
+    if ('cache_control' in block) return true;
+  }
+  return false;
+}
+
+/**
+ * Checks if a message's content has Anthropic cache_control fields.
+ */
+function hasAnthropicCacheControl(content: MessageContentComplex[]): boolean {
+  for (let i = 0; i < content.length; i++) {
+    if ('cache_control' in content[i]) return true;
+  }
+  return false;
+}
+
+/**
+ * Checks if a message's content has Bedrock cachePoint blocks.
+ */
+function hasBedrockCachePoint(content: MessageContentComplex[]): boolean {
+  for (let i = 0; i < content.length; i++) {
+    if (isCachePoint(content[i])) return true;
+  }
+  return false;
+}
+
 /**
  * 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,
  * then adds fresh cache control to the last 2 user messages in a single backward pass.
  * This ensures we don't accumulate stale cache points across multiple turns.
+ * Returns a new array - only clones messages that require modification.
  * @param messages - The array of message objects.
- * @returns - The updated array of message objects with cache control added.
+ * @returns - A new array of message objects with cache control added.
  */
 export function addCacheControl<T extends AnthropicMessage | BaseMessage>(
   messages: T[]
@@ -33,68 +141,82 @@ export function addCacheControl<T extends AnthropicMessage | BaseMessage>(
     return messages;
   }
 
-  const updatedMessages = [...messages];
+  const updatedMessages: T[] = [...messages];
   let userMessagesModified = 0;
 
   for (let i = updatedMessages.length - 1; i >= 0; i--) {
-    const message = updatedMessages[i];
+    const originalMessage = updatedMessages[i];
+    const content = originalMessage.content;
     const isUserMessage =
-      ('getType' in message && message.getType() === 'human') ||
-      ('role' in message && message.role === 'user');
+      ('getType' in originalMessage && originalMessage.getType() === 'human') ||
+      ('role' in originalMessage && originalMessage.role === 'user');
+
+    const hasArrayContent = Array.isArray(content);
+    const needsStripping =
+      hasArrayContent &&
+      needsCacheStripping(content as MessageContentComplex[]);
+    const needsCacheAdd =
+      userMessagesModified < 2 &&
+      isUserMessage &&
+      (typeof content === 'string' || hasArrayContent);
+
+    if (!needsStripping && !needsCacheAdd) {
+      continue;
+    }
 
-    if (Array.isArray(message.content)) {
-      message.content = message.content.filter(
-        (block) => !isCachePoint(block as MessageContentComplex)
-      ) as typeof message.content;
+    let workingContent: MessageContentComplex[];
 
-      for (let j = 0; j < message.content.length; j++) {
-        const block = message.content[j] as Record<string, unknown>;
+    if (hasArrayContent) {
+      workingContent = deepCloneContent(
+        content as MessageContentComplex[]
+      ).filter((block) => !isCachePoint(block as MessageContentComplex));
+
+      for (let j = 0; j < workingContent.length; j++) {
+        const block = workingContent[j] as Record<string, unknown>;
         if ('cache_control' in block) {
           delete block.cache_control;
         }
       }
+    } else if (typeof content === 'string') {
+      workingContent = [
+        { type: 'text', text: content },
+      ] as MessageContentComplex[];
+    } else {
+      workingContent = [];
     }
 
     if (userMessagesModified >= 2 || !isUserMessage) {
+      updatedMessages[i] = cloneMessage(
+        originalMessage as MessageWithContent,
+        workingContent
+      ) as T;
       continue;
     }
 
-    if (typeof message.content === 'string') {
-      message.content = [
-        {
-          type: 'text',
-          text: message.content,
-          cache_control: { type: 'ephemeral' },
-        },
-      ];
-      userMessagesModified++;
-    } else if (Array.isArray(message.content)) {
-      for (let j = message.content.length - 1; j >= 0; j--) {
-        const contentPart = message.content[j];
-        if ('type' in contentPart && contentPart.type === 'text') {
-          (contentPart as Anthropic.TextBlockParam).cache_control = {
-            type: 'ephemeral',
-          };
-          userMessagesModified++;
-          break;
-        }
+    for (let j = workingContent.length - 1; j >= 0; j--) {
+      const contentPart = workingContent[j];
+      if ('type' in contentPart && contentPart.type === 'text') {
+        (contentPart as Anthropic.TextBlockParam).cache_control = {
+          type: 'ephemeral',
+        };
+        userMessagesModified++;
+        break;
       }
     }
+
+    updatedMessages[i] = cloneMessage(
+      originalMessage as MessageWithContent,
+      workingContent
+    ) as T;
   }
 
   return updatedMessages;
 }
 
-/**
- * Checks if a content block is a cache point
- */
-function isCachePoint(block: MessageContentComplex): boolean {
-  return 'cachePoint' in block && !('type' in block);
-}
-
 /**
  * Removes all Anthropic cache_control fields from messages
  * Used when switching from Anthropic to Bedrock provider
+ * Returns a new array - only clones messages that require modification.
  */
 export function stripAnthropicCacheControl<T extends MessageWithContent>(
   messages: T[]
@@ -103,20 +225,24 @@ export function stripAnthropicCacheControl<T extends MessageWithContent>(
     return messages;
   }
 
-  const updatedMessages = [...messages];
+  const updatedMessages: T[] = [...messages];
 
   for (let i = 0; i < updatedMessages.length; i++) {
-    const message = updatedMessages[i];
-    const content = message.content;
+    const originalMessage = updatedMessages[i];
+    const content = originalMessage.content;
 
-    if (Array.isArray(content)) {
-      for (let j = 0; j < content.length; j++) {
-        const block = content[j] as Record<string, unknown>;
-        if ('cache_control' in block) {
-          delete block.cache_control;
-        }
+    if (!Array.isArray(content) || !hasAnthropicCacheControl(content)) {
+      continue;
+    }
+
+    const clonedContent = deepCloneContent(content);
+    for (let j = 0; j < clonedContent.length; j++) {
+      const block = clonedContent[j] as Record<string, unknown>;
+      if ('cache_control' in block) {
+        delete block.cache_control;
       }
     }
+    updatedMessages[i] = cloneMessage(originalMessage, clonedContent) as T;
   }
 
   return updatedMessages;
@@ -125,6 +251,7 @@ export function stripAnthropicCacheControl<T extends MessageWithContent>(
 /**
  * Removes all Bedrock cachePoint blocks from messages
  * Used when switching from Bedrock to Anthropic provider
+ * Returns a new array - only clones messages that require modification.
  */
 export function stripBedrockCacheControl<T extends MessageWithContent>(
   messages: T[]
@@ -133,17 +260,20 @@ export function stripBedrockCacheControl<T extends MessageWithContent>(
     return messages;
   }
 
-  const updatedMessages = [...messages];
+  const updatedMessages: T[] = [...messages];
 
   for (let i = 0; i < updatedMessages.length; i++) {
-    const message = updatedMessages[i];
-    const content = message.content;
+    const originalMessage = updatedMessages[i];
+    const content = originalMessage.content;
 
-    if (Array.isArray(content)) {
-      message.content = content.filter(
-        (block) => !isCachePoint(block as MessageContentComplex)
-      ) as typeof content;
+    if (!Array.isArray(content) || !hasBedrockCachePoint(content)) {
+      continue;
     }
+
+    const clonedContent = deepCloneContent(content).filter(
+      (block) => !isCachePoint(block as MessageContentComplex)
+    );
+    updatedMessages[i] = cloneMessage(originalMessage, clonedContent) as T;
   }
 
   return updatedMessages;

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/schemas/index.ts

@@ -0,0 +1,2 @@
+// src/schemas/index.ts
+export * from './validate';