@illuma-ai/agents 1.4.0-alpha.6 → 1.5.1

package/src/llm/anthropic/utils/server-tool-inputs.test.ts

@@ -0,0 +1,436 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import { _convertMessagesToAnthropicPayload } from './message_inputs';
+
+describe('_convertMessagesToAnthropicPayload — server tool use (web search) multi-turn', () => {
+  /* Skipped: this fork intentionally diverged from the reference implementation's
+   * `_convertLangChainToolCallToAnthropic` — local always emits
+   * `tool_use` regardless of `srvtoolu_` ID prefix (see message_inputs.ts
+   * line ~144). These tests assert the standard server_tool_use emission
+   * which this fork does not implement. The text→server_tool_use correction
+   * test (next, "corrects text-typed server tool blocks") still passes
+   * because that path lives in `_formatContent`. */
+  it.skip('corrects tool_use blocks with srvtoolu_ IDs to server_tool_use', () => {
+    const messageHistory: BaseMessage[] = [
+      new HumanMessage('search for X and Y'),
+      new AIMessage({
+        content: [
+          { type: 'text', text: 'I will search for that.' },
+          {
+            type: 'tool_use',
+            id: 'srvtoolu_1',
+            name: 'web_search',
+            input: { query: 'X' },
+          },
+          {
+            type: 'web_search_tool_result',
+            tool_use_id: 'srvtoolu_1',
+            content: [
+              {
+                type: 'web_search_result',
+                url: 'https://example.com',
+                title: 'Result',
+                encrypted_content: 'abc',
+                page_age: '1d',
+              },
+            ],
+          },
+          {
+            type: 'tool_use',
+            id: 'srvtoolu_2',
+            name: 'web_search',
+            input: { query: 'Y' },
+          },
+          {
+            type: 'web_search_tool_result',
+            tool_use_id: 'srvtoolu_2',
+            content: [
+              {
+                type: 'web_search_result',
+                url: 'https://example2.com',
+                title: 'Result 2',
+                encrypted_content: 'def',
+                page_age: '2d',
+              },
+            ],
+          },
+          { type: 'text', text: 'Here are the results.' },
+        ],
+        tool_calls: [
+          {
+            id: 'srvtoolu_1',
+            name: 'web_search',
+            args: { query: 'X' },
+            type: 'tool_call',
+          },
+          {
+            id: 'srvtoolu_2',
+            name: 'web_search',
+            args: { query: 'Y' },
+            type: 'tool_call',
+          },
+        ],
+      }),
+      new HumanMessage('follow up question'),
+    ];
+
+    const { messages } = _convertMessagesToAnthropicPayload(messageHistory);
+    expect(messages).toHaveLength(3);
+
+    const assistantContent = messages[1].content as any[];
+    const serverToolBlocks = assistantContent.filter(
+      (b: any) => b.type === 'server_tool_use'
+    );
+    const searchResultBlocks = assistantContent.filter(
+      (b: any) => b.type === 'web_search_tool_result'
+    );
+    const regularToolUseBlocks = assistantContent.filter(
+      (b: any) => b.type === 'tool_use' && b.id?.startsWith('srvtoolu_')
+    );
+
+    expect(serverToolBlocks).toHaveLength(2);
+    expect(searchResultBlocks).toHaveLength(2);
+    expect(regularToolUseBlocks).toHaveLength(0);
+
+    // Verify blocks are clean (no extra streaming properties)
+    for (const b of serverToolBlocks) {
+      expect(Object.keys(b).sort()).toEqual(
+        ['id', 'input', 'name', 'type'].sort()
+      );
+    }
+    for (const b of searchResultBlocks) {
+      expect(Object.keys(b).sort()).toEqual(
+        ['content', 'tool_use_id', 'type'].sort()
+      );
+    }
+  });
+
+  it('corrects text-typed server tool blocks back to correct types', () => {
+    const messageHistory: BaseMessage[] = [
+      new HumanMessage('search for X'),
+      new AIMessage({
+        content: [
+          {
+            type: 'text',
+            id: 'srvtoolu_1',
+            name: 'web_search',
+            input: '{"query":"X"}',
+          },
+          {
+            type: 'text',
+            tool_use_id: 'srvtoolu_1',
+            content: [
+              {
+                type: 'web_search_result',
+                url: 'https://example.com',
+                title: 'Result',
+                encrypted_content: 'abc',
+                page_age: '1d',
+              },
+            ],
+          },
+          { type: 'text', text: 'Found results.' },
+        ],
+        tool_calls: [
+          {
+            id: 'srvtoolu_1',
+            name: 'web_search',
+            args: { query: 'X' },
+            type: 'tool_call',
+          },
+        ],
+      }),
+      new HumanMessage('follow up'),
+    ];
+
+    const { messages } = _convertMessagesToAnthropicPayload(messageHistory);
+    const assistantContent = messages[1].content as any[];
+
+    expect(assistantContent[0]).toEqual({
+      type: 'server_tool_use',
+      id: 'srvtoolu_1',
+      name: 'web_search',
+      input: { query: 'X' },
+    });
+    expect(assistantContent[1].type).toBe('web_search_tool_result');
+    expect(assistantContent[1].tool_use_id).toBe('srvtoolu_1');
+    expect(assistantContent[2]).toEqual({
+      type: 'text',
+      text: 'Found results.',
+    });
+  });
+
+  /* Skipped: depends on the standard server_tool_use emission, see header. */
+  it.skip('filters server tool calls when content is a string', () => {
+    const messageHistory: BaseMessage[] = [
+      new HumanMessage('search for X'),
+      new AIMessage({
+        content: 'I searched and found results.',
+        tool_calls: [
+          {
+            id: 'srvtoolu_1',
+            name: 'web_search',
+            args: { query: 'X' },
+            type: 'tool_call',
+          },
+          {
+            id: 'toolu_regular',
+            name: 'calculator',
+            args: { expr: '2+2' },
+            type: 'tool_call',
+          },
+        ],
+      }),
+      new ToolMessage({
+        content: '4',
+        tool_call_id: 'toolu_regular',
+      }),
+      new HumanMessage('follow up'),
+    ];
+
+    const { messages } = _convertMessagesToAnthropicPayload(messageHistory);
+    const assistantContent = messages[1].content as any[];
+
+    const toolUseBlocks = assistantContent.filter(
+      (b: any) => b.type === 'tool_use'
+    );
+    expect(toolUseBlocks).toHaveLength(1);
+    expect(toolUseBlocks[0].id).toBe('toolu_regular');
+
+    const serverToolBlocks = assistantContent.filter((b: any) =>
+      b.id?.startsWith('srvtoolu_')
+    );
+    expect(serverToolBlocks).toHaveLength(0);
+  });
+
+  /* Skipped: depends on the standard server_tool_use emission, see header. */
+  it.skip('handles empty string content with only server tool calls', () => {
+    const messageHistory: BaseMessage[] = [
+      new HumanMessage('search for X'),
+      new AIMessage({
+        content: '',
+        tool_calls: [
+          {
+            id: 'srvtoolu_1',
+            name: 'web_search',
+            args: { query: 'X' },
+            type: 'tool_call',
+          },
+        ],
+      }),
+      new HumanMessage('follow up'),
+    ];
+
+    const { messages } = _convertMessagesToAnthropicPayload(messageHistory);
+    const assistantContent = messages[1].content as any[];
+    expect(assistantContent).toHaveLength(1);
+    expect(assistantContent[0].type).toBe('text');
+    expect(assistantContent[0].text).toBe(' ');
+  });
+
+  /* Skipped: depends on the standard server_tool_use emission, see header. */
+  it.skip('preserves regular tool_use blocks alongside corrected server tool blocks', () => {
+    const messageHistory: BaseMessage[] = [
+      new HumanMessage('search for X and calculate 2+2'),
+      new AIMessage({
+        content: [
+          { type: 'text', text: 'Let me help.' },
+          {
+            type: 'tool_use',
+            id: 'srvtoolu_1',
+            name: 'web_search',
+            input: { query: 'X' },
+          },
+          {
+            type: 'web_search_tool_result',
+            tool_use_id: 'srvtoolu_1',
+            content: [
+              {
+                type: 'web_search_result',
+                url: 'https://example.com',
+                title: 'Result',
+                encrypted_content: 'abc',
+                page_age: '1d',
+              },
+            ],
+          },
+          {
+            type: 'tool_use',
+            id: 'toolu_calc',
+            name: 'calculator',
+            input: { expr: '2+2' },
+          },
+        ],
+        tool_calls: [
+          {
+            id: 'srvtoolu_1',
+            name: 'web_search',
+            args: { query: 'X' },
+            type: 'tool_call',
+          },
+          {
+            id: 'toolu_calc',
+            name: 'calculator',
+            args: { expr: '2+2' },
+            type: 'tool_call',
+          },
+        ],
+      }),
+      new ToolMessage({
+        content: '4',
+        tool_call_id: 'toolu_calc',
+      }),
+      new HumanMessage('follow up'),
+    ];
+
+    const { messages } = _convertMessagesToAnthropicPayload(messageHistory);
+    const assistantContent = messages[1].content as any[];
+
+    const serverToolUse = assistantContent.filter(
+      (b: any) => b.type === 'server_tool_use'
+    );
+    const webSearchResult = assistantContent.filter(
+      (b: any) => b.type === 'web_search_tool_result'
+    );
+    const regularToolUse = assistantContent.filter(
+      (b: any) => b.type === 'tool_use' && !b.id?.startsWith('srvtoolu_')
+    );
+
+    expect(serverToolUse).toHaveLength(1);
+    expect(serverToolUse[0].id).toBe('srvtoolu_1');
+    expect(webSearchResult).toHaveLength(1);
+    expect(regularToolUse).toHaveLength(1);
+    expect(regularToolUse[0].id).toBe('toolu_calc');
+  });
+
+  it('filters out empty text blocks from array content', () => {
+    const messageHistory: BaseMessage[] = [
+      new HumanMessage('search for X'),
+      new AIMessage({
+        content: [
+          { type: 'text', text: '' },
+          {
+            type: 'server_tool_use',
+            id: 'srvtoolu_1',
+            name: 'web_search',
+            input: { query: 'X' },
+          },
+          {
+            type: 'web_search_tool_result',
+            tool_use_id: 'srvtoolu_1',
+            content: [
+              {
+                type: 'web_search_result',
+                url: 'https://example.com',
+                title: 'Result',
+                encrypted_content: 'abc',
+                page_age: '1d',
+              },
+            ],
+          },
+          { type: 'text', text: '' },
+          { type: 'text', text: 'Here are the results.' },
+        ],
+        tool_calls: [
+          {
+            id: 'srvtoolu_1',
+            name: 'web_search',
+            args: { query: 'X' },
+            type: 'tool_call',
+          },
+        ],
+      }),
+      new HumanMessage('follow up'),
+    ];
+
+    const { messages } = _convertMessagesToAnthropicPayload(messageHistory);
+    const assistantContent = messages[1].content as any[];
+
+    const emptyTextBlocks = assistantContent.filter(
+      (b: any) => b.type === 'text' && b.text === ''
+    );
+    expect(emptyTextBlocks).toHaveLength(0);
+
+    const textBlocks = assistantContent.filter((b: any) => b.type === 'text');
+    expect(textBlocks).toHaveLength(1);
+    expect(textBlocks[0].text).toBe('Here are the results.');
+  });
+
+  /**
+   * Regression for discussion #12806.
+   *
+   * Anthropic web_search responses can include text blocks whose text is
+   * whitespace-only (e.g. ' ', '\n', '\t') alongside server_tool_use and
+   * web_search_tool_result blocks. On follow-up turns the API rejects these
+   * with: "messages: text content blocks must contain non-whitespace text".
+   *
+   * The empty-string check alone is insufficient — the filter must drop any
+   * text block whose trimmed content is empty.
+   */
+  it.each([
+    ['single space', ' '],
+    ['newline', '\n'],
+    ['tab', '\t'],
+    ['multiple spaces', '   '],
+    ['mixed whitespace', ' \n\t '],
+  ])(
+    'filters whitespace-only text blocks from array content (%s)',
+    (_label, whitespace) => {
+      const messageHistory: BaseMessage[] = [
+        new HumanMessage('search for X'),
+        new AIMessage({
+          content: [
+            { type: 'text', text: whitespace },
+            {
+              type: 'server_tool_use',
+              id: 'srvtoolu_1',
+              name: 'web_search',
+              input: { query: 'X' },
+            },
+            {
+              type: 'web_search_tool_result',
+              tool_use_id: 'srvtoolu_1',
+              content: [
+                {
+                  type: 'web_search_result',
+                  url: 'https://example.com',
+                  title: 'Result',
+                  encrypted_content: 'abc',
+                  page_age: '1d',
+                },
+              ],
+            },
+            { type: 'text', text: 'Here are the results.' },
+          ],
+          tool_calls: [
+            {
+              id: 'srvtoolu_1',
+              name: 'web_search',
+              args: { query: 'X' },
+              type: 'tool_call',
+            },
+          ],
+        }),
+        new HumanMessage('follow up'),
+      ];
+
+      const { messages } = _convertMessagesToAnthropicPayload(messageHistory);
+      const assistantContent = messages[1].content as any[];
+
+      const whitespaceTextBlocks = assistantContent.filter(
+        (b: any) =>
+          b.type === 'text' &&
+          typeof b.text === 'string' &&
+          b.text.trim() === ''
+      );
+      expect(whitespaceTextBlocks).toHaveLength(0);
+
+      const textBlocks = assistantContent.filter(
+        (b: any) => b.type === 'text'
+      );
+      expect(textBlocks).toHaveLength(1);
+      expect(textBlocks[0].text).toBe('Here are the results.');
+    }
+  );
+});

package/src/llm/bedrock/__tests__/bedrock-caching.test.ts

@@ -194,6 +194,134 @@ describe('Bedrock Prompt Caching', () => {
         expect(model.promptCache).toBe(false);
       });
     });
+
+    describe('Tool cache strategies', () => {
+      const fakeTools = [
+        {
+          toolSpec: {
+            name: 'web_search',
+            description: 'core search',
+            inputSchema: { json: { type: 'object', properties: {} } },
+          },
+        },
+        {
+          toolSpec: {
+            name: 'execute_code',
+            description: 'core code',
+            inputSchema: { json: { type: 'object', properties: {} } },
+          },
+        },
+        {
+          toolSpec: {
+            name: 'search_emails_mcp_Outlook',
+            description: 'mcp tool',
+            inputSchema: { json: { type: 'object', properties: {} } },
+          },
+        },
+        {
+          toolSpec: {
+            name: 'list_documents_mcp_SharePoint',
+            description: 'mcp tool',
+            inputSchema: { json: { type: 'object', properties: {} } },
+          },
+        },
+      ];
+
+      it("default 'single' strategy: one cachePoint at end of tools array", () => {
+        const model = new CustomChatBedrockConverse({
+          model: 'anthropic.claude-3-haiku-20240307-v1:0',
+          region: 'us-east-1',
+          promptCache: true,
+          // toolCacheStrategy omitted — default is 'single'
+        });
+        const params = model.invocationParams({
+          tools: fakeTools,
+        } satisfies InvocationParamsOptions);
+        // 4 tools + 1 cachePoint
+        expect(params.toolConfig?.tools).toHaveLength(5);
+        expect(params.toolConfig?.tools?.[4]).toEqual({
+          cachePoint: { type: 'default' },
+        });
+      });
+
+      it("'split' strategy with toolGroupSelector groups tools by selector key, cachePoint after each group", () => {
+        const model = new CustomChatBedrockConverse({
+          model: 'anthropic.claude-3-haiku-20240307-v1:0',
+          region: 'us-east-1',
+          promptCache: true,
+          toolCacheStrategy: 'split',
+          toolGroupSelector: (toolName) =>
+            toolName.includes('_mcp_') ? 'mcp' : 'core',
+        });
+        const params = model.invocationParams({
+          tools: fakeTools,
+        } satisfies InvocationParamsOptions);
+        // [core, core, cp, mcp, mcp, cp] = 6 entries
+        expect(params.toolConfig?.tools).toHaveLength(6);
+        expect(params.toolConfig?.tools?.[0]).toEqual(fakeTools[0]); // core
+        expect(params.toolConfig?.tools?.[1]).toEqual(fakeTools[1]); // core
+        expect(params.toolConfig?.tools?.[2]).toEqual({
+          cachePoint: { type: 'default' },
+        });
+        expect(params.toolConfig?.tools?.[3]).toEqual(fakeTools[2]); // mcp
+        expect(params.toolConfig?.tools?.[4]).toEqual(fakeTools[3]); // mcp
+        expect(params.toolConfig?.tools?.[5]).toEqual({
+          cachePoint: { type: 'default' },
+        });
+      });
+
+      it("'none' strategy: no cachePoint added at all", () => {
+        const model = new CustomChatBedrockConverse({
+          model: 'anthropic.claude-3-haiku-20240307-v1:0',
+          region: 'us-east-1',
+          promptCache: true,
+          toolCacheStrategy: 'none',
+        });
+        const params = model.invocationParams({
+          tools: fakeTools,
+        } satisfies InvocationParamsOptions);
+        expect(params.toolConfig?.tools).toHaveLength(4);
+        for (const tool of params.toolConfig?.tools ?? []) {
+          expect('cachePoint' in tool).toBe(false);
+        }
+      });
+
+      it("'split' with single-group selector behaves like 'single'", () => {
+        const model = new CustomChatBedrockConverse({
+          model: 'anthropic.claude-3-haiku-20240307-v1:0',
+          region: 'us-east-1',
+          promptCache: true,
+          toolCacheStrategy: 'split',
+          toolGroupSelector: () => 'all', // every tool same group
+        });
+        const params = model.invocationParams({
+          tools: fakeTools,
+        } satisfies InvocationParamsOptions);
+        // 4 tools + 1 cachePoint
+        expect(params.toolConfig?.tools).toHaveLength(5);
+        expect(params.toolConfig?.tools?.[4]).toEqual({
+          cachePoint: { type: 'default' },
+        });
+      });
+
+      it("'split' with empty groups skipped (only emits cachePoint after non-empty groups)", () => {
+        const model = new CustomChatBedrockConverse({
+          model: 'anthropic.claude-3-haiku-20240307-v1:0',
+          region: 'us-east-1',
+          promptCache: true,
+          toolCacheStrategy: 'split',
+          toolGroupSelector: (name) =>
+            name.includes('_mcp_') ? 'mcp' : 'core',
+        });
+        // Only core tools — no MCP
+        const coreOnly = fakeTools.slice(0, 2);
+        const params = model.invocationParams({
+          tools: coreOnly,
+        } satisfies InvocationParamsOptions);
+        // 2 core + 1 cachePoint = 3
+        expect(params.toolConfig?.tools).toHaveLength(3);
+      });
+    });
   });
 
   describe('AgentContext - System Message Caching', () => {
@@ -233,7 +361,13 @@ describe('Bedrock Prompt Caching', () => {
     };
 
     describe('Bedrock system message with promptCache: true', () => {
-      it('should produce plain string system message (cachePoint is handled at tool level)', async () => {
+      /* Updated contract (2026-05-01, PR #128 alignment): Bedrock
+       * system message gets a `cachePoint` block inline so the system
+       * prefix is cached at the AWS account level (cross-user). Previously
+       * cachePoint was only added at the tool level, leaving the system
+       * prefix uncached. Tools array still gets its own cachePoints from
+       * IllumaBedrockConverse.invocationParams independently. */
+      it('emits content array with cachePoint after stable text (Claude model)', async () => {
         const ctx = createBedrockContext({
           instructions: 'You are a helpful assistant.',
           promptCache: true,
@@ -242,17 +376,20 @@ describe('Bedrock Prompt Caching', () => {
         const systemRunnable = ctx.systemRunnable;
         expect(systemRunnable).toBeDefined();
 
-        // Invoke the runnable to get the messages
         const result = await systemRunnable!.invoke([]);
         const systemMessage = result[0];
 
-        // Bedrock system messages are plain strings — cachePoint is added
-        // at the tool level by IllumaBedrockConverse.invocationParams()
-        expect(typeof systemMessage.content).toBe('string');
-        expect(systemMessage.content).toBe('You are a helpful assistant.');
+        const content = systemMessage.content as Array<Record<string, unknown>>;
+        expect(Array.isArray(content)).toBe(true);
+        expect(content).toHaveLength(2);
+        expect(content[0]).toEqual({
+          type: 'text',
+          text: 'You are a helpful assistant.',
+        });
+        expect(content[1]).toEqual({ cachePoint: { type: 'default', ttl: '5m' } });
       });
 
-      it('should include combined instructions and additional_instructions as plain string', async () => {
+      it('keeps additional_instructions AFTER cachePoint (dynamic tail not cached)', async () => {
         const ctx = createBedrockContext({
           instructions: 'Base instructions.',
           additionalInstructions: 'Additional context.',
@@ -261,11 +398,20 @@ describe('Bedrock Prompt Caching', () => {
 
         const result = await ctx.systemRunnable!.invoke([]);
         const systemMessage = result[0];
+        const content = systemMessage.content as Array<Record<string, unknown>>;
 
-        // Bedrock system messages are plain strings even with promptCache
-        expect(typeof systemMessage.content).toBe('string');
-        expect(systemMessage.content).toContain('Base instructions.');
-        expect(systemMessage.content).toContain('Additional context.');
+        /* Order is critical: stable text → cachePoint → dynamic text.
+         * Anything after the cachePoint is excluded from the cache, so
+         * the per-user/per-request `additional_instructions` does not
+         * invalidate the cached prefix. */
+        expect(content).toHaveLength(3);
+        expect((content[0] as { text: string }).text).toBe(
+          'Base instructions.'
+        );
+        expect(content[1]).toEqual({ cachePoint: { type: 'default', ttl: '5m' } });
+        expect((content[2] as { text: string }).text).toBe(
+          'Additional context.'
+        );
       });
     });
 
@@ -312,7 +458,7 @@ describe('Bedrock Prompt Caching', () => {
         expect(content[0]).toEqual({
           type: 'text',
           text: 'You are a helpful assistant.',
-          cache_control: { type: 'ephemeral' },
+          cache_control: { type: 'ephemeral', ttl: '5m' },
         });
       });
 
@@ -330,19 +476,21 @@ describe('Bedrock Prompt Caching', () => {
     });
 
     describe('Provider-specific caching behavior', () => {
-      it('should produce plain string for Bedrock (cachePoint handled at tool level)', async () => {
+      it('emits cachePoint block inline for Bedrock Claude (account-scoped system caching)', async () => {
         const bedrockCtx = createBedrockContext({
           instructions: 'Test',
           promptCache: true,
         });
 
         const result = await bedrockCtx.systemRunnable!.invoke([]);
+        const content = result[0].content as Array<Record<string, unknown>>;
 
-        // Bedrock system messages are plain strings — cachePoint is added
-        // at the tool level by IllumaBedrockConverse.invocationParams(),
-        // not inline in the system message content
-        expect(typeof result[0].content).toBe('string');
-        expect(result[0].content).toBe('Test');
+        // Bedrock system messages now carry an inline cachePoint so the
+        // system prefix gets cached at the AWS account level (matching
+        // PR #128). Tool-level cachePoint from
+        // IllumaBedrockConverse.invocationParams() runs independently.
+        expect(Array.isArray(content)).toBe(true);
+        expect(content.some((c) => 'cachePoint' in c)).toBe(true);
       });
 
       it('should use cache_control format for Anthropic, not cachePoint', async () => {