@illuma-ai/agents 1.0.89 → 1.0.93

package/src/llm/bedrock/llm.spec.ts

@@ -5,16 +5,24 @@ config();
 import { expect, test, describe, jest } from '@jest/globals';
 import {
   AIMessage,
-  AIMessageChunk,
+  ToolMessage,
   HumanMessage,
   SystemMessage,
-  ToolMessage,
+  AIMessageChunk,
 } from '@langchain/core/messages';
 import { concat } from '@langchain/core/utils/stream';
 import { ChatGenerationChunk } from '@langchain/core/outputs';
-import { BedrockRuntimeClient } from '@aws-sdk/client-bedrock-runtime';
+import {
+  BedrockRuntimeClient,
+  ConverseCommand,
+} from '@aws-sdk/client-bedrock-runtime';
+import type { ConverseResponse } from '@aws-sdk/client-bedrock-runtime';
+import {
+  convertConverseMessageToLangChainMessage,
+  handleConverseStreamMetadata,
+  convertToConverseMessages,
+} from './utils';
 import { CustomChatBedrockConverse, ServiceTierType } from './index';
-import { convertToConverseMessages } from './utils';
 
 jest.setTimeout(120000);
 
@@ -212,47 +220,6 @@ describe('CustomChatBedrockConverse', () => {
       return model as any;
     }
 
-    test('should detect contentBlockIndex at top level', () => {
-      const model = getModelWithCleanMethods();
-      const objWithIndex = { contentBlockIndex: 0, text: 'hello' };
-      const objWithoutIndex = { text: 'hello' };
-
-      expect(model.hasContentBlockIndex(objWithIndex)).toBe(true);
-      expect(model.hasContentBlockIndex(objWithoutIndex)).toBe(false);
-    });
-
-    test('should detect contentBlockIndex in nested objects', () => {
-      const model = getModelWithCleanMethods();
-      const nestedWithIndex = {
-        outer: {
-          inner: {
-            contentBlockIndex: 1,
-            data: 'test',
-          },
-        },
-      };
-      const nestedWithoutIndex = {
-        outer: {
-          inner: {
-            data: 'test',
-          },
-        },
-      };
-
-      expect(model.hasContentBlockIndex(nestedWithIndex)).toBe(true);
-      expect(model.hasContentBlockIndex(nestedWithoutIndex)).toBe(false);
-    });
-
-    test('should return false for null, undefined, and primitives', () => {
-      const model = getModelWithCleanMethods();
-
-      expect(model.hasContentBlockIndex(null)).toBe(false);
-      expect(model.hasContentBlockIndex(undefined)).toBe(false);
-      expect(model.hasContentBlockIndex('string')).toBe(false);
-      expect(model.hasContentBlockIndex(123)).toBe(false);
-      expect(model.hasContentBlockIndex(true)).toBe(false);
-    });
-
     test('should remove contentBlockIndex from top level', () => {
       const model = getModelWithCleanMethods();
       const obj = {
@@ -315,7 +282,160 @@ describe('CustomChatBedrockConverse', () => {
       expect(model.removeContentBlockIndex(undefined)).toBeUndefined();
     });
 
-    test('processChunk should remove contentBlockIndex from AIMessageChunk response_metadata', () => {
+    test('enrichChunk should strip contentBlockIndex from response_metadata', () => {
+      const model = getModelWithCleanMethods();
+
+      const chunkWithIndex = new ChatGenerationChunk({
+        text: 'Hello',
+        message: new AIMessageChunk({
+          content: 'Hello',
+          response_metadata: {
+            contentBlockIndex: 0,
+            stopReason: null,
+          },
+        }),
+      });
+
+      const enriched = model.enrichChunk(chunkWithIndex, new Set([0]));
+
+      expect(enriched.message.response_metadata).toEqual({
+        stopReason: null,
+      });
+      expect(
+        (enriched.message.response_metadata as any).contentBlockIndex
+      ).toBeUndefined();
+      expect(enriched.text).toBe('Hello');
+    });
+
+    test('enrichChunk should pass through chunks without contentBlockIndex unchanged', () => {
+      const model = getModelWithCleanMethods();
+
+      const chunkWithoutIndex = new ChatGenerationChunk({
+        text: 'Hello',
+        message: new AIMessageChunk({
+          content: 'Hello',
+          response_metadata: {
+            stopReason: 'end_turn',
+            usage: { inputTokens: 10, outputTokens: 5 },
+          },
+        }),
+      });
+
+      const enriched = model.enrichChunk(chunkWithoutIndex, new Set());
+
+      expect(enriched.message.response_metadata).toEqual({
+        stopReason: 'end_turn',
+        usage: { inputTokens: 10, outputTokens: 5 },
+      });
+    });
+
+    test('enrichChunk should inject index on array content blocks', () => {
+      const model = getModelWithCleanMethods();
+
+      const chunkWithArrayContent = new ChatGenerationChunk({
+        text: '',
+        message: new AIMessageChunk({
+          content: [
+            {
+              type: 'reasoning_content',
+              reasoningText: { text: 'thinking...' },
+            },
+          ],
+          response_metadata: {
+            contentBlockIndex: 0,
+          },
+        }),
+      });
+
+      const enriched = model.enrichChunk(chunkWithArrayContent, new Set([0]));
+
+      expect(Array.isArray(enriched.message.content)).toBe(true);
+      const blocks = enriched.message.content as any[];
+      expect(blocks[0].index).toBe(0);
+      expect(blocks[0].type).toBe('reasoning_content');
+      expect(
+        (enriched.message.response_metadata as any).contentBlockIndex
+      ).toBeUndefined();
+    });
+
+    test('enrichChunk should promote text to array when multiple block indices seen', () => {
+      const model = getModelWithCleanMethods();
+
+      const textChunk = new ChatGenerationChunk({
+        text: 'Hello world',
+        message: new AIMessageChunk({
+          content: 'Hello world',
+          response_metadata: {
+            contentBlockIndex: 1,
+          },
+        }),
+      });
+
+      const enriched = model.enrichChunk(textChunk, new Set([0, 1]));
+
+      expect(Array.isArray(enriched.message.content)).toBe(true);
+      const blocks = enriched.message.content as any[];
+      expect(blocks).toHaveLength(1);
+      expect(blocks[0]).toEqual({
+        type: 'text',
+        text: 'Hello world',
+        index: 1,
+      });
+    });
+
+    test('enrichChunk should keep text as string when only one block index seen', () => {
+      const model = getModelWithCleanMethods();
+
+      const textChunk = new ChatGenerationChunk({
+        text: 'Hello',
+        message: new AIMessageChunk({
+          content: 'Hello',
+          response_metadata: {
+            contentBlockIndex: 0,
+            stopReason: null,
+          },
+        }),
+      });
+
+      const enriched = model.enrichChunk(textChunk, new Set([0]));
+
+      expect(typeof enriched.message.content).toBe('string');
+      expect(enriched.message.content).toBe('Hello');
+    });
+
+    test('enrichChunk should strip deeply nested contentBlockIndex from response_metadata', () => {
+      const model = getModelWithCleanMethods();
+
+      const chunkWithNestedIndex = new ChatGenerationChunk({
+        text: 'Test',
+        message: new AIMessageChunk({
+          content: 'Test',
+          response_metadata: {
+            contentBlockIndex: 0,
+            amazon: {
+              bedrock: {
+                contentBlockIndex: 0,
+                trace: { something: 'value' },
+              },
+            },
+            otherData: 'preserved',
+          },
+        }),
+      });
+
+      const enriched = model.enrichChunk(chunkWithNestedIndex, new Set([0]));
+
+      expect(enriched.message.response_metadata).toEqual({
+        amazon: {
+          bedrock: {
+            trace: { something: 'value' },
+          },
+        },
+        otherData: 'preserved',
+      });
+    });
+
+    test('enrichChunk should remove contentBlockIndex from AIMessageChunk response_metadata', () => {
       const model = getModelWithCleanMethods();
 
       const chunkWithIndex = new ChatGenerationChunk({
@@ -329,18 +449,19 @@ describe('CustomChatBedrockConverse', () => {
         }),
       });
 
-      const cleaned = model.processChunk(chunkWithIndex);
+      const cleaned = model.enrichChunk(chunkWithIndex, new Set([0]));
 
       expect(cleaned.message.response_metadata).toEqual({
         stopReason: null,
       });
       expect(
-        (cleaned.message.response_metadata as any).contentBlockIndex
+        (cleaned.message.response_metadata as Record<string, unknown>)
+          .contentBlockIndex
       ).toBeUndefined();
       expect(cleaned.text).toBe('Hello');
     });
 
-    test('processChunk should pass through chunks without contentBlockIndex unchanged', () => {
+    test('enrichChunk should pass through chunks without contentBlockIndex unchanged', () => {
       const model = getModelWithCleanMethods();
 
       const chunkWithoutIndex = new ChatGenerationChunk({
@@ -354,7 +475,7 @@ describe('CustomChatBedrockConverse', () => {
         }),
       });
 
-      const cleaned = model.processChunk(chunkWithoutIndex);
+      const cleaned = model.enrichChunk(chunkWithoutIndex, new Set([0]));
 
       expect(cleaned.message.response_metadata).toEqual({
         stopReason: 'end_turn',
@@ -362,7 +483,7 @@ describe('CustomChatBedrockConverse', () => {
       });
     });
 
-    test('processChunk should handle deeply nested contentBlockIndex in response_metadata', () => {
+    test('enrichChunk should handle deeply nested contentBlockIndex in response_metadata', () => {
       const model = getModelWithCleanMethods();
 
       const chunkWithNestedIndex = new ChatGenerationChunk({
@@ -370,6 +491,7 @@ describe('CustomChatBedrockConverse', () => {
         message: new AIMessageChunk({
           content: 'Test',
           response_metadata: {
+            contentBlockIndex: 0,
             amazon: {
               bedrock: {
                 contentBlockIndex: 0,
@@ -381,7 +503,7 @@ describe('CustomChatBedrockConverse', () => {
         }),
       });
 
-      const cleaned = model.processChunk(chunkWithNestedIndex);
+      const cleaned = model.enrichChunk(chunkWithNestedIndex, new Set([0]));
 
       expect(cleaned.message.response_metadata).toEqual({
         amazon: {
@@ -395,6 +517,164 @@ describe('CustomChatBedrockConverse', () => {
   });
 });
 
+describe('handleConverseStreamMetadata - cache token extraction', () => {
+  test('should extract cacheReadInputTokens and cacheWriteInputTokens into input_token_details', () => {
+    const metadata = {
+      usage: {
+        inputTokens: 13,
+        outputTokens: 5,
+        totalTokens: 10849,
+        cacheReadInputTokens: 10831,
+        cacheWriteInputTokens: 0,
+      },
+      metrics: { latencyMs: 1000 },
+    };
+
+    const chunk = handleConverseStreamMetadata(metadata, {
+      streamUsage: true,
+    });
+    const msg = chunk.message as AIMessageChunk;
+
+    expect(msg.usage_metadata).toEqual({
+      input_tokens: 13,
+      output_tokens: 5,
+      total_tokens: 10849,
+      input_token_details: {
+        cache_read: 10831,
+        cache_creation: 0,
+      },
+    });
+  });
+
+  test('should not include input_token_details when no cache tokens present', () => {
+    const metadata = {
+      usage: {
+        inputTokens: 100,
+        outputTokens: 50,
+        totalTokens: 150,
+      },
+      metrics: { latencyMs: 500 },
+    };
+
+    const chunk = handleConverseStreamMetadata(metadata, {
+      streamUsage: true,
+    });
+    const msg = chunk.message as AIMessageChunk;
+
+    expect(msg.usage_metadata).toEqual({
+      input_tokens: 100,
+      output_tokens: 50,
+      total_tokens: 150,
+    });
+    expect(msg.usage_metadata?.input_token_details).toBeUndefined();
+  });
+
+  test('should include input_token_details when only cacheWriteInputTokens is present', () => {
+    const metadata = {
+      usage: {
+        inputTokens: 50,
+        outputTokens: 10,
+        totalTokens: 10060,
+        cacheWriteInputTokens: 10000,
+      },
+      metrics: { latencyMs: 800 },
+    };
+
+    const chunk = handleConverseStreamMetadata(metadata, {
+      streamUsage: true,
+    });
+    const msg = chunk.message as AIMessageChunk;
+
+    expect(msg.usage_metadata?.input_token_details).toEqual({
+      cache_read: 0,
+      cache_creation: 10000,
+    });
+  });
+
+  test('should return undefined usage_metadata when streamUsage is false', () => {
+    const metadata = {
+      usage: {
+        inputTokens: 13,
+        outputTokens: 5,
+        totalTokens: 10849,
+        cacheReadInputTokens: 10831,
+        cacheWriteInputTokens: 0,
+      },
+      metrics: { latencyMs: 1000 },
+    };
+
+    const chunk = handleConverseStreamMetadata(metadata, {
+      streamUsage: false,
+    });
+    const msg = chunk.message as AIMessageChunk;
+
+    expect(msg.usage_metadata).toBeUndefined();
+  });
+});
+
+describe('convertConverseMessageToLangChainMessage - cache token extraction', () => {
+  const makeResponseMetadata = (
+    usage: Record<string, number>
+  ): Omit<ConverseResponse, 'output'> =>
+    ({
+      usage,
+      stopReason: 'end_turn',
+      metrics: undefined,
+      $metadata: { requestId: 'test-id' },
+    }) as unknown as Omit<ConverseResponse, 'output'>;
+
+  test('should extract cache tokens in non-streaming response', () => {
+    const message = {
+      role: 'assistant' as const,
+      content: [{ text: 'Hello!' }],
+    };
+
+    const result = convertConverseMessageToLangChainMessage(
+      message,
+      makeResponseMetadata({
+        inputTokens: 20,
+        outputTokens: 5,
+        totalTokens: 10856,
+        cacheReadInputTokens: 10831,
+        cacheWriteInputTokens: 0,
+      })
+    );
+
+    expect(result.usage_metadata).toEqual({
+      input_tokens: 20,
+      output_tokens: 5,
+      total_tokens: 10856,
+      input_token_details: {
+        cache_read: 10831,
+        cache_creation: 0,
+      },
+    });
+  });
+
+  test('should not include input_token_details when no cache tokens in non-streaming response', () => {
+    const message = {
+      role: 'assistant' as const,
+      content: [{ text: 'Hello!' }],
+    };
+
+    const result = convertConverseMessageToLangChainMessage(
+      message,
+      makeResponseMetadata({
+        inputTokens: 100,
+        outputTokens: 50,
+        totalTokens: 150,
+      })
+    );
+
+    expect(result.usage_metadata).toEqual({
+      input_tokens: 100,
+      output_tokens: 50,
+      total_tokens: 150,
+    });
+    expect(result.usage_metadata?.input_token_details).toBeUndefined();
+  });
+});
+
 describe('convertToConverseMessages', () => {
   test('should convert basic messages', () => {
     const { converseMessages, converseSystem } = convertToConverseMessages([
@@ -613,4 +893,67 @@ describe.skip('Integration tests', () => {
       expect(reasoningBlocks.length).toBeGreaterThanOrEqual(0);
     }
   });
+
+  test('cache tokens should populate input_token_details', async () => {
+    const client = new BedrockRuntimeClient({
+      region: integrationArgs.region,
+      credentials: integrationArgs.credentials,
+    });
+
+    // Large system prompt (>1024 tokens) to meet Bedrock's minimum cache threshold
+    const largeSystemPrompt = [
+      'You are an expert assistant.',
+      ...Array(200).fill(
+        'This is padding content to exceed the minimum token threshold for Bedrock prompt caching. '
+      ),
+      'When answering, be brief and direct.',
+    ].join(' ');
+
+    const systemBlocks = [
+      { text: largeSystemPrompt },
+      { cachePoint: { type: 'default' as const } },
+    ];
+
+    const converseArgs = {
+      modelId: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
+      system: systemBlocks,
+      inferenceConfig: { maxTokens: 50 },
+    };
+
+    // Call 1: populate the cache (may be a write or read if already warm)
+    await client.send(
+      new ConverseCommand({
+        ...converseArgs,
+        messages: [{ role: 'user', content: [{ text: 'Say hello.' }] }],
+      })
+    );
+
+    // Call 2: should read from cache — this is the one we assert on
+    const response = await client.send(
+      new ConverseCommand({
+        ...converseArgs,
+        messages: [
+          { role: 'user', content: [{ text: 'Say hello.' }] },
+          { role: 'assistant', content: [{ text: 'Hello!' }] },
+          { role: 'user', content: [{ text: 'Say goodbye.' }] },
+        ],
+      })
+    );
+
+    // Feed raw response through convertConverseMessageToLangChainMessage
+    const result = convertConverseMessageToLangChainMessage(
+      response.output!.message!,
+      response
+    );
+
+    expect(result.usage_metadata).toBeDefined();
+    expect(result.usage_metadata!.input_tokens).toBeGreaterThan(0);
+    expect(result.usage_metadata!.output_tokens).toBeGreaterThan(0);
+
+    // Cache should have been populated by call 1, so call 2 should show cache reads
+    expect(result.usage_metadata!.input_token_details).toBeDefined();
+    expect(
+      result.usage_metadata!.input_token_details!.cache_read
+    ).toBeGreaterThan(0);
+  });
 });

package/src/llm/bedrock/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/src/llm/bedrock/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":""}

package/src/llm/bedrock/utils/index.js

@@ -0,0 +1,6 @@
+/**
+ * Bedrock Converse utility exports.
+ */
+export { convertToConverseMessages, extractImageInfo, langchainReasoningBlockToBedrockReasoningBlock, concatenateLangchainReasoningBlocks, } from './message_inputs';
+export { convertConverseMessageToLangChainMessage, handleConverseStreamContentBlockStart, handleConverseStreamContentBlockDelta, handleConverseStreamMetadata, bedrockReasoningBlockToLangchainReasoningBlock, bedrockReasoningDeltaToLangchainPartialReasoningBlock, } from './message_outputs';
+//# sourceMappingURL=index.js.map

package/src/llm/bedrock/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,yBAAyB,EACzB,gBAAgB,EAChB,8CAA8C,EAC9C,mCAAmC,GACpC,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,wCAAwC,EACxC,qCAAqC,EACrC,qCAAqC,EACrC,4BAA4B,EAC5B,8CAA8C,EAC9C,qDAAqD,GACtD,MAAM,mBAAmB,CAAC"}