fix(aws): map Bedrock prompt cache usage metadata (langchain-ai#10839)

## Summary

`ChatBedrockConverse` currently drops Bedrock prompt-caching usage
fields (`cacheReadInputTokens` and `cacheWriteInputTokens`) when
building LangChain usage metadata.

This change maps those fields into `usage_metadata.input_token_details`
for both invoke and stream metadata paths so cache behavior is visible
in LangSmith and downstream cost/usage analytics.

## Changes

- `@langchain/aws`
- Updated `convertConverseMessageToLangChainMessage` to map:
  - `cacheReadInputTokens` -> `input_token_details.cache_read`
  - `cacheWriteInputTokens` -> `input_token_details.cache_creation`
- Updated `handleConverseStreamMetadata` to emit the same cache token
details in streaming usage metadata.
- Added focused unit tests covering:
  - non-stream cache token mapping
  - stream cache token mapping
- omission of `input_token_details` when Bedrock cache fields are absent

Author: hntrl

.changeset/hunter-aws-prompt-cache-usage.md

@@ -0,0 +1,9 @@
+---
+"@langchain/aws": patch
+---
+
+fix(aws): map Bedrock prompt cache usage metadata to input token details
+
+Include `cacheReadInputTokens` and `cacheWriteInputTokens` from Bedrock Converse
+responses in `usage_metadata.input_token_details` for both invoke and stream
+metadata handling.

libs/providers/langchain-aws/src/utils/message_outputs.ts

@@ -33,13 +33,24 @@ export function convertConverseMessageToLangChainMessage(
   }
   let tokenUsage: UsageMetadata | undefined;
   if (responseMetadata.usage) {
+    const inputTokenDetails = {
+      ...(responseMetadata.usage.cacheReadInputTokens !== undefined && {
+        cache_read: responseMetadata.usage.cacheReadInputTokens,
+      }),
+      ...(responseMetadata.usage.cacheWriteInputTokens !== undefined && {
+        cache_creation: responseMetadata.usage.cacheWriteInputTokens,
+      }),
+    };
     const input_tokens = responseMetadata.usage.inputTokens ?? 0;
     const output_tokens = responseMetadata.usage.outputTokens ?? 0;
     tokenUsage = {
       input_tokens,
       output_tokens,
       total_tokens:
         responseMetadata.usage.totalTokens ?? input_tokens + output_tokens,
+      input_token_details: Object.keys(inputTokenDetails).length
+        ? inputTokenDetails
+        : undefined,
     };
   }
 
@@ -193,12 +204,23 @@ export function handleConverseStreamMetadata(
     streamUsage: boolean;
   }
 ): ChatGenerationChunk {
+  const inputTokenDetails = {
+    ...(metadata.usage?.cacheReadInputTokens !== undefined && {
+      cache_read: metadata.usage.cacheReadInputTokens,
+    }),
+    ...(metadata.usage?.cacheWriteInputTokens !== undefined && {
+      cache_creation: metadata.usage.cacheWriteInputTokens,
+    }),
+  };
   const inputTokens = metadata.usage?.inputTokens ?? 0;
   const outputTokens = metadata.usage?.outputTokens ?? 0;
   const usage_metadata: UsageMetadata = {
     input_tokens: inputTokens,
     output_tokens: outputTokens,
     total_tokens: metadata.usage?.totalTokens ?? inputTokens + outputTokens,
+    input_token_details: Object.keys(inputTokenDetails).length
+      ? inputTokenDetails
+      : undefined,
   };
   return new ChatGenerationChunk({
     text: "",

libs/providers/langchain-aws/src/utils/tests/message_outputs.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "vitest";
+import type * as Bedrock from "@aws-sdk/client-bedrock-runtime";
+import {
+  convertConverseMessageToLangChainMessage,
+  handleConverseStreamMetadata,
+} from "../message_outputs.js";
+
+describe("message output usage metadata conversion", () => {
+  test("maps Bedrock prompt cache tokens for non-stream responses", () => {
+    const message: Bedrock.Message = {
+      role: "assistant",
+      content: [{ text: "Hello" }],
+    };
+    const responseMetadata = {
+      usage: {
+        inputTokens: 10,
+        outputTokens: 5,
+        totalTokens: 15,
+        cacheReadInputTokens: 7,
+        cacheWriteInputTokens: 3,
+      },
+    } as Omit<Bedrock.ConverseResponse, "output">;
+
+    const result = convertConverseMessageToLangChainMessage(
+      message,
+      responseMetadata
+    );
+
+    expect(result.usage_metadata).toEqual({
+      input_tokens: 10,
+      output_tokens: 5,
+      total_tokens: 15,
+      input_token_details: {
+        cache_read: 7,
+        cache_creation: 3,
+      },
+    });
+  });
+
+  test("does not add input_token_details when Bedrock cache fields are absent", () => {
+    const message: Bedrock.Message = {
+      role: "assistant",
+      content: [{ text: "Hello" }],
+    };
+    const responseMetadata = {
+      usage: {
+        inputTokens: 10,
+        outputTokens: 5,
+        totalTokens: 15,
+      },
+    } as Omit<Bedrock.ConverseResponse, "output">;
+
+    const result = convertConverseMessageToLangChainMessage(
+      message,
+      responseMetadata
+    );
+
+    expect(result.usage_metadata?.input_token_details).toBeUndefined();
+  });
+
+  test("maps Bedrock prompt cache tokens for stream metadata", () => {
+    const result = handleConverseStreamMetadata(
+      {
+        usage: {
+          inputTokens: 20,
+          outputTokens: 4,
+          totalTokens: 24,
+          cacheReadInputTokens: 9,
+          cacheWriteInputTokens: 6,
+        },
+      },
+      { streamUsage: true }
+    );
+
+    expect(result.message.usage_metadata).toEqual({
+      input_tokens: 20,
+      output_tokens: 4,
+      total_tokens: 24,
+      input_token_details: {
+        cache_read: 9,
+        cache_creation: 6,
+      },
+    });
+  });
+});