Fix whitespace-only text block from orphaned CacheBreakpoint (#4839)

When a CacheBreakpoint had no preceding content block to attach
cache_control to, rawContentToAnthropicContent created a placeholder
{ type: 'text', text: ' ' } block. The Anthropic API rejects
whitespace-only text blocks with 'text content block must contain
non-whitespace text'.

This happens in long conversations after prompt-tsx prunes content to
fit the token budget, leaving a CacheBreakpoint with no real content
before it.

Fix: defer the cache_control to the next cacheable content block. If
no subsequent block exists, silently drop it (nothing to cache anyway).

Fixes microsoft/vscode#305956

Author: bhavyaus

src/platform/endpoint/node/messagesApi.ts

@@ -381,6 +381,8 @@ function tryParseToolReferences(content: ContentBlockParam[], validToolNames?: S
 
 function rawContentToAnthropicContent(content: readonly Raw.ChatCompletionContentPart[]): ContentBlockParam[] {
 	const convertedContent: ContentBlockParam[] = [];
+	// Track pending cache_control that couldn't be attached to a preceding block
+	let pendingCacheControl = false;
 
 	for (const part of content) {
 		switch (part.type) {
@@ -419,12 +421,12 @@ function rawContentToAnthropicContent(content: readonly Raw.ChatCompletionConten
 				if (previousBlock && contentBlockSupportsCacheControl(previousBlock)) {
 					previousBlock.cache_control = { type: 'ephemeral' };
 				} else {
-					// Empty string is invalid
-					convertedContent.push({
-						type: 'text',
-						text: ' ',
-						cache_control: { type: 'ephemeral' }
-					});
+					// No preceding block to attach to — defer until the next
+					// cacheable content block is added, or silently drop it.
+					// Previously this created a whitespace-only text block which
+					// the Anthropic API rejects with "text content block must
+					// contain non-whitespace text".
+					pendingCacheControl = true;
 				}
 				break;
 			}
@@ -467,6 +469,15 @@ function rawContentToAnthropicContent(content: readonly Raw.ChatCompletionConten
 				break;
 			}
 		}
+
+		// Attach any pending cache_control to the block we just added
+		if (pendingCacheControl && convertedContent.length > 0) {
+			const lastBlock = convertedContent.at(-1)!;
+			if (contentBlockSupportsCacheControl(lastBlock)) {
+				lastBlock.cache_control = { type: 'ephemeral' };
+				pendingCacheControl = false;
+			}
+		}
 	}
 
 	return convertedContent;

src/platform/endpoint/test/node/messagesApi.spec.ts

@@ -370,10 +370,33 @@ suite('rawMessagesToMessagesAPI', function () {
 
 		const toolResult = findToolResult(result.messages);
 		expect(toolResult).toBeDefined();
-		expect(toolResult!.cache_control).toEqual({ type: 'ephemeral' });
-		// The dummy whitespace-only text block should be filtered out
+		// Orphaned cache breakpoint with no content to attach to is silently dropped
+		expect(toolResult!.cache_control).toBeUndefined();
 		expect(toolResult!.content).toBeUndefined();
 	});
+
+	test('cache breakpoint before content defers cache_control to next block', function () {
+		const messages: Raw.ChatMessage[] = [
+			{
+				role: Raw.ChatRole.User,
+				content: [
+					{ type: Raw.ChatCompletionContentPartKind.CacheBreakpoint, cacheType: 'ephemeral' },
+					{ type: Raw.ChatCompletionContentPartKind.Text, text: 'hello world' },
+				],
+			},
+		];
+
+		const result = rawMessagesToMessagesAPI(messages);
+
+		expect(result.messages).toHaveLength(1);
+		const content = assertContentArray(result.messages[0].content);
+		expect(content).toHaveLength(1);
+		expect(content[0]).toEqual({
+			type: 'text',
+			text: 'hello world',
+			cache_control: { type: 'ephemeral' },
+		});
+	});
 });
 
 suite('addToolsAndSystemCacheControl', function () {