add changeset, defensive clamp, regroup cache tests

- patch changeset for #509 fix
- clamp noCache at 0 if cached_tokens > prompt_tokens
- group prompt_tokens_details cases under their own describe block
- add intent comment explaining the OpenAI-style cached_tokens convention

Made-with: Cursor

Author: threepointone

.changeset/workers-ai-usage-cache-tokens.md

@@ -0,0 +1,9 @@
+---
+"workers-ai-provider": patch
+---
+
+Map `inputTokens.cacheRead` and `inputTokens.noCache` from Workers AI's `usage.prompt_tokens_details.cached_tokens` instead of always reporting them as `undefined`. This makes prompt-cache hits visible to consumers that compute pricing or telemetry from `LanguageModelV3Usage` (`generateText`/`streamText` `result.usage`).
+
+`cached_tokens` is treated as `cacheRead`; `cacheWrite` remains `undefined` because the OpenAI-style usage shape Workers AI returns does not distinguish cache reads from writes.
+
+Closes [#509](https://github.com/cloudflare/ai/issues/509).

packages/workers-ai-provider/src/map-workersai-usage.ts

@@ -3,6 +3,11 @@ import type { LanguageModelV3Usage } from "@ai-sdk/provider";
 /**
  * Map Workers AI usage data to the AI SDK V3 usage format.
  * Accepts any object that may have a `usage` property with token counts.
+ *
+ * Workers AI mirrors the OpenAI usage shape, including
+ * `prompt_tokens_details.cached_tokens` for prompt-cache hits. OpenAI-style
+ * responses don't distinguish cache reads from cache writes, so we treat
+ * `cached_tokens` as `cacheRead` and leave `cacheWrite` undefined.
  */
 export function mapWorkersAIUsage(
 	output: Record<string, unknown> | AiTextGenerationOutput | AiTextToImageOutput,
@@ -24,6 +29,11 @@ export function mapWorkersAIUsage(
 	const completionTokens = usage.completion_tokens ?? 0;
 	const cachedTokens = usage.prompt_tokens_details?.cached_tokens;
 
+	// Clamp at 0 in case the provider ever reports cached_tokens > prompt_tokens;
+	// the v3 spec expects non-negative counts.
+	const noCache =
+		cachedTokens !== undefined ? Math.max(0, promptTokens - cachedTokens) : undefined;
+
 	return {
 		outputTokens: {
 			total: completionTokens,
@@ -32,7 +42,7 @@ export function mapWorkersAIUsage(
 		},
 		inputTokens: {
 			total: promptTokens,
-			noCache: cachedTokens !== undefined ? promptTokens - cachedTokens : undefined,
+			noCache,
 			cacheRead: cachedTokens,
 			cacheWrite: undefined,
 		},

packages/workers-ai-provider/test/map-workersai-usage.test.ts

@@ -71,55 +71,70 @@ describe("mapWorkersAIUsage", () => {
 		expect(result.outputTokens.total).toBe(10);
 	});
 
-	it("should map cacheRead and noCache when prompt_tokens_details is present", () => {
-		const result = mapWorkersAIUsage({
-			usage: {
-				prompt_tokens: 6377,
-				completion_tokens: 349,
-				prompt_tokens_details: { cached_tokens: 2861 },
-			},
+	describe("with prompt_tokens_details", () => {
+		it("maps cached_tokens to cacheRead and computes noCache", () => {
+			const result = mapWorkersAIUsage({
+				usage: {
+					prompt_tokens: 6377,
+					completion_tokens: 349,
+					prompt_tokens_details: { cached_tokens: 2861 },
+				},
+			});
+
+			expect(result.inputTokens.cacheRead).toBe(2861);
+			expect(result.inputTokens.noCache).toBe(6377 - 2861);
+			expect(result.inputTokens.cacheWrite).toBeUndefined();
 		});
 
-		expect(result.inputTokens.cacheRead).toBe(2861);
-		expect(result.inputTokens.noCache).toBe(6377 - 2861);
-		expect(result.inputTokens.cacheWrite).toBeUndefined();
-	});
-
-	it("should handle cached_tokens of 0 (all tokens uncached)", () => {
-		const result = mapWorkersAIUsage({
-			usage: {
-				prompt_tokens: 100,
-				completion_tokens: 50,
-				prompt_tokens_details: { cached_tokens: 0 },
-			},
+		it("treats cached_tokens=0 as a real signal (not 'unknown')", () => {
+			const result = mapWorkersAIUsage({
+				usage: {
+					prompt_tokens: 100,
+					completion_tokens: 50,
+					prompt_tokens_details: { cached_tokens: 0 },
+				},
+			});
+
+			expect(result.inputTokens.cacheRead).toBe(0);
+			expect(result.inputTokens.noCache).toBe(100);
 		});
 
-		expect(result.inputTokens.cacheRead).toBe(0);
-		expect(result.inputTokens.noCache).toBe(100 - 0);
-	});
+		it("falls back to undefined when cached_tokens is absent", () => {
+			const result = mapWorkersAIUsage({
+				usage: {
+					prompt_tokens: 100,
+					completion_tokens: 50,
+					prompt_tokens_details: {},
+				},
+			});
+
+			expect(result.inputTokens.cacheRead).toBeUndefined();
+			expect(result.inputTokens.noCache).toBeUndefined();
+		});
 
-	it("should handle prompt_tokens_details with missing cached_tokens", () => {
-		const result = mapWorkersAIUsage({
-			usage: {
-				prompt_tokens: 100,
-				completion_tokens: 50,
-				prompt_tokens_details: {},
-			},
+		it("clamps noCache at 0 when cached_tokens > prompt_tokens", () => {
+			const result = mapWorkersAIUsage({
+				usage: {
+					prompt_tokens: 100,
+					completion_tokens: 10,
+					prompt_tokens_details: { cached_tokens: 150 },
+				},
+			});
+
+			expect(result.inputTokens.noCache).toBe(0);
+			expect(result.inputTokens.cacheRead).toBe(150);
 		});
 
-		expect(result.inputTokens.cacheRead).toBeUndefined();
-		expect(result.inputTokens.noCache).toBeUndefined();
-	});
+		it("does not let cache fields affect raw.total", () => {
+			const result = mapWorkersAIUsage({
+				usage: {
+					prompt_tokens: 1000,
+					completion_tokens: 200,
+					prompt_tokens_details: { cached_tokens: 800 },
+				},
+			});
 
-	it("should compute raw total correctly regardless of cache fields", () => {
-		const result = mapWorkersAIUsage({
-			usage: {
-				prompt_tokens: 1000,
-				completion_tokens: 200,
-				prompt_tokens_details: { cached_tokens: 800 },
-			},
+			expect(result.raw).toEqual({ total: 1200 });
 		});
-
-		expect(result.raw).toEqual({ total: 1000 + 200 });
 	});
 });