refactor: improve handling of tool_calls and add unit tests for session options normalization (#4779)

Author: osortega

src/extension/chatSessions/vscode-node/copilotCloudSessionContentBuilder.ts

@@ -222,13 +222,14 @@ export class ChatSessionContentBuilder {
 	): string {
 		let currentResponseContent = '';
 		if (delta.role === 'assistant') {
+			const toolCalls = Array.isArray(delta.tool_calls) ? delta.tool_calls : undefined;
 			// Handle special case for run_custom_setup_step
 			if (
 				choice.finish_reason === 'tool_calls' &&
-				delta.tool_calls?.length &&
-				(delta.tool_calls[0].function.name === 'run_custom_setup_step' || delta.tool_calls[0].function.name === 'run_setup')
+				toolCalls?.length &&
+				(toolCalls[0].function.name === 'run_custom_setup_step' || toolCalls[0].function.name === 'run_setup')
 			) {
-				const toolCall = delta.tool_calls[0];
+				const toolCall = toolCalls[0];
 				let args: { name?: string } = {};
 				try {
 					args = JSON.parse(toolCall.function.arguments);
@@ -254,14 +255,14 @@ export class ChatSessionContentBuilder {
 				}
 
 				const isError = delta.content?.startsWith('<error>');
-				if (delta.tool_calls) {
+				if (toolCalls) {
 					// Add any accumulated content as markdown first
 					if (currentResponseContent.trim()) {
 						responseParts.push(new ChatResponseMarkdownPart(currentResponseContent.trim()));
 						currentResponseContent = '';
 					}
 
-					for (const toolCall of delta.tool_calls) {
+					for (const toolCall of toolCalls) {
 						const toolPart = this.createToolInvocationPart(pullRequest, toolCall, delta.content || '');
 						if (toolPart) {
 							responseParts.push(toolPart);

src/extension/chatSessions/vscode-node/copilotCloudSessionsProvider.ts

@@ -27,7 +27,7 @@ import { isUntitledSessionId } from '../common/utils';
 import { IChatDelegationSummaryService } from '../copilotcli/common/delegationSummaryService';
 import { body_suffix, CONTINUE_TRUNCATION, extractTitle, formatBodyPlaceholder, getAuthorDisplayName, getRepoId, JOBS_API_VERSION, SessionIdForPr, toOpenPullRequestWebviewUri, truncatePrompt } from '../vscode/copilotCodingAgentUtils';
 import { CopilotCloudGitOperationsManager } from './copilotCloudGitOperationsManager';
-import { ChatSessionContentBuilder } from './copilotCloudSessionContentBuilder';
+import { ChatSessionContentBuilder, SessionResponseLogChunk } from './copilotCloudSessionContentBuilder';
 import { IPullRequestFileChangesService } from './pullRequestFileChangesService';
 import MarkdownIt = require('markdown-it');
 
@@ -39,6 +39,11 @@ interface ConfirmationMetadata {
 	chatContext: vscode.ChatContext;
 }
 
+type InitialSessionOption = {
+	readonly optionId: string;
+	readonly value: string | vscode.ChatSessionProviderOptionItem;
+};
+
 function validateMetadata(metadata: unknown): asserts metadata is ConfirmationMetadata {
 	if (typeof metadata !== 'object') {
 		throw new Error('Invalid confirmation metadata: not an object.');
@@ -54,6 +59,82 @@ function validateMetadata(metadata: unknown): asserts metadata is ConfirmationMe
 	}
 }
 
+function describeRuntimeValue(value: unknown): string {
+	if (Array.isArray(value)) {
+		return `array(length=${value.length})`;
+	}
+
+	if (value === null) {
+		return 'null';
+	}
+
+	if (value === undefined) {
+		return 'undefined';
+	}
+
+	if (typeof value === 'object') {
+		const keys = Object.keys(value);
+		return `object(keys=${keys.slice(0, 5).join(',')}${keys.length > 5 ? ',…' : ''})`;
+	}
+
+	return typeof value;
+}
+
+function isOptionItemValue(value: unknown): value is vscode.ChatSessionProviderOptionItem {
+	return typeof value === 'object' && value !== null && 'id' in value && typeof value.id === 'string';
+}
+
+function isInitialSessionOption(value: unknown): value is InitialSessionOption {
+	if (typeof value !== 'object' || value === null || !('optionId' in value) || typeof value.optionId !== 'string' || !('value' in value)) {
+		return false;
+	}
+
+	return typeof value.value === 'string' || isOptionItemValue(value.value);
+}
+
+export function normalizeInitialSessionOptions(initialOptions: unknown, logService?: ILogService, chatResource?: vscode.Uri): readonly InitialSessionOption[] {
+	if (!initialOptions) {
+		return [];
+	}
+
+	if (Array.isArray(initialOptions)) {
+		const normalized = initialOptions.filter(isInitialSessionOption);
+		if (logService && normalized.length !== initialOptions.length) {
+			logService.warn(`[chatParticipantImpl] Ignoring ${initialOptions.length - normalized.length} malformed initialSessionOptions entries for ${chatResource?.toString() ?? 'unknown-resource'}. Received ${describeRuntimeValue(initialOptions)}.`);
+		}
+
+		return normalized;
+	}
+
+	if (typeof initialOptions === 'object') {
+		const normalized: InitialSessionOption[] = [];
+		for (const [optionId, value] of Object.entries(initialOptions)) {
+			if (isInitialSessionOption(value)) {
+				normalized.push(value);
+			} else if (typeof value === 'string' || isOptionItemValue(value)) {
+				normalized.push({ optionId, value });
+			}
+		}
+
+		if (normalized.length > 0) {
+			logService?.warn(`[chatParticipantImpl] Coerced object-shaped initialSessionOptions for ${chatResource?.toString() ?? 'unknown-resource'}. Received ${describeRuntimeValue(initialOptions)} and recovered ${normalized.length} entries.`);
+			return normalized;
+		}
+	}
+
+	logService?.warn(`[chatParticipantImpl] Ignoring unsupported initialSessionOptions for ${chatResource?.toString() ?? 'unknown-resource'}. Received ${describeRuntimeValue(initialOptions)}.`);
+	return [];
+}
+
+export function parseSessionLogChunksSafely(rawText: string, logService: ILogService, parser: (value: string) => SessionResponseLogChunk[]): SessionResponseLogChunk[] {
+	try {
+		return parser(rawText);
+	} catch (error) {
+		logService.error(error instanceof Error ? error : new Error(String(error)), `[streamNewLogContent] Failed to parse streamed log content (${rawText.length} chars).`);
+		return [];
+	}
+}
+
 const CUSTOM_AGENTS_OPTION_GROUP_ID = 'customAgents';
 const MODELS_OPTION_GROUP_ID = 'models';
 const PARTNER_AGENTS_OPTION_GROUP_ID = 'partnerAgents';
@@ -1841,8 +1922,11 @@ export class CopilotCloudSessionsProvider extends Disposable implements vscode.C
 		const chatResource = context.chatSessionContext?.chatSessionItem?.resource;
 
 		const initialOptions = context.chatSessionContext?.initialSessionOptions;
-		if (chatResource && initialOptions) {
-			for (const opt of initialOptions) {
+		if (chatResource) {
+			this.logService.trace(`[chatParticipantImpl] initialSessionOptions for ${chatResource.toString()}: ${describeRuntimeValue(initialOptions)}`);
+		}
+		if (chatResource) {
+			for (const opt of normalizeInitialSessionOptions(initialOptions, this.logService, chatResource)) {
 				const value = typeof opt.value === 'string' ? opt.value : opt.value.id;
 				if (opt.optionId === CUSTOM_AGENTS_OPTION_GROUP_ID) {
 					this.sessionCustomAgentMap.set(chatResource, value);
@@ -2152,19 +2236,32 @@ export class CopilotCloudSessionsProvider extends Disposable implements vscode.C
 
 			// Parse the new log content
 			const contentBuilder = new ChatSessionContentBuilder(CopilotCloudSessionsProvider.TYPE, this._gitService);
-
-			const logChunks = contentBuilder.parseSessionLogs(newLogContent);
+			const logChunks = parseSessionLogChunksSafely(newLogContent, this.logService, value => contentBuilder.parseSessionLogs(value));
 			let hasStreamedContent = false;
 			let hasSetupStepProgress = false;
 
-			for (const chunk of logChunks) {
+			for (const [chunkIndex, chunk] of logChunks.entries()) {
+				if (!Array.isArray(chunk.choices)) {
+					this.logService.warn(`[streamNewLogContent] Ignoring chunk ${chunkIndex} with non-array choices for PR #${pullRequest.number}.`);
+					continue;
+				}
+
 				for (const choice of chunk.choices) {
+					if (!choice?.delta) {
+						this.logService.warn(`[streamNewLogContent] Ignoring chunk ${chunkIndex} with missing delta for PR #${pullRequest.number}.`);
+						continue;
+					}
+
 					const delta = choice.delta;
+					const toolCalls = Array.isArray(delta.tool_calls) ? delta.tool_calls : undefined;
+					if (delta.tool_calls && !toolCalls) {
+						this.logService.warn(`[streamNewLogContent] Ignoring non-array tool_calls for PR #${pullRequest.number}.`);
+					}
 
 					if (delta.role === 'assistant') {
 						// Handle special case for run_custom_setup_step/run_setup
-						if (choice.finish_reason === 'tool_calls' && delta.tool_calls?.length && (delta.tool_calls[0].function.name === 'run_custom_setup_step' || delta.tool_calls[0].function.name === 'run_setup')) {
-							const toolCall = delta.tool_calls[0];
+						if (choice.finish_reason === 'tool_calls' && toolCalls?.length && (toolCalls[0].function.name === 'run_custom_setup_step' || toolCalls[0].function.name === 'run_setup')) {
+							const toolCall = toolCalls[0];
 							let args: any = {};
 							try {
 								args = JSON.parse(toolCall.function.arguments);
@@ -2195,8 +2292,8 @@ export class CopilotCloudSessionsProvider extends Disposable implements vscode.C
 								}
 							}
 
-							if (delta.tool_calls) {
-								for (const toolCall of delta.tool_calls) {
+							if (toolCalls) {
+								for (const toolCall of toolCalls) {
 									const toolPart = contentBuilder.createToolInvocationPart(pullRequest, toolCall, delta.content || '');
 									if (toolPart) {
 										stream.push(toolPart);

src/extension/chatSessions/vscode-node/test/copilotCloudSessionsProvider.spec.ts

@@ -0,0 +1,156 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { describe, expect, it, vi } from 'vitest';
+import * as vscode from 'vscode';
+import { IGitService } from '../../../../platform/git/common/gitService';
+import { PullRequestSearchItem, SessionInfo } from '../../../../platform/github/common/githubAPI';
+import { TestLogService } from '../../../../platform/testing/common/testLogService';
+import { mock } from '../../../../util/common/test/simpleMock';
+import { ChatResponseMarkdownPart, ChatResponseTurn2 } from '../../../../vscodeTypes';
+import { ChatSessionContentBuilder } from '../copilotCloudSessionContentBuilder';
+import { normalizeInitialSessionOptions, parseSessionLogChunksSafely } from '../copilotCloudSessionsProvider';
+
+vi.mock('vscode', async () => {
+	const actual = await import('../../../../vscodeTypes');
+	return {
+		...actual,
+		workspace: {
+			workspaceFolders: [],
+		},
+	};
+});
+
+class RecordingLogService extends TestLogService {
+	override readonly trace = vi.fn();
+	override readonly warn = vi.fn();
+	override readonly error = vi.fn();
+}
+
+class TestGitService extends mock<IGitService>() {
+	declare readonly _serviceBrand: undefined;
+	override activeRepository = { get: () => undefined } as IGitService['activeRepository'];
+	override initialize = vi.fn(async () => { });
+	override repositories = [];
+}
+
+function createPullRequest(): PullRequestSearchItem {
+	return {
+		id: 'pr-1',
+		number: 1,
+		title: 'Test PR',
+		state: 'OPEN',
+		url: 'https://example.com/pr/1',
+		createdAt: '2026-03-27T00:00:00Z',
+		updatedAt: '2026-03-27T00:00:00Z',
+		author: { login: 'octocat' },
+		repository: {
+			owner: { login: 'microsoft' },
+			name: 'vscode',
+		},
+		additions: 1,
+		deletions: 0,
+		files: { totalCount: 1 },
+		fullDatabaseId: 1,
+		headRefOid: 'abc123',
+		body: 'Body',
+	};
+}
+
+function createSession(state: SessionInfo['state'] = 'completed'): SessionInfo {
+	return {
+		id: 'session-1',
+		name: 'Cloud session',
+		user_id: 1,
+		agent_id: 1,
+		logs: '',
+		logs_blob_id: 'blob-1',
+		state,
+		owner_id: 1,
+		repo_id: 1,
+		resource_type: 'pull_request',
+		resource_id: 1,
+		last_updated_at: '2026-03-27T00:00:00Z',
+		created_at: '2026-03-27T00:00:00Z',
+		completed_at: '2026-03-27T00:00:00Z',
+		event_type: 'pull_request',
+		workflow_run_id: 1,
+		premium_requests: 0,
+		error: null,
+		resource_global_id: 'global-1',
+	};
+}
+
+describe('copilotCloudSessionsProvider helpers', () => {
+	it('coerces object-shaped initialSessionOptions into option entries', () => {
+		const logService = new RecordingLogService();
+		const sessionResource = vscode.Uri.parse('copilot-cloud-agent:/1');
+
+		const result = normalizeInitialSessionOptions({
+			models: { id: 'gpt-4.1', name: 'GPT-4.1' },
+			repositories: 'microsoft/vscode',
+		}, logService, sessionResource);
+
+		expect(result).toEqual([
+			{ optionId: 'models', value: { id: 'gpt-4.1', name: 'GPT-4.1' } },
+			{ optionId: 'repositories', value: 'microsoft/vscode' },
+		]);
+		expect(logService.warn).toHaveBeenCalledWith(expect.stringContaining('Coerced object-shaped initialSessionOptions'));
+	});
+
+	it('ignores unsupported initialSessionOptions payloads and logs a warning', () => {
+		const logService = new RecordingLogService();
+
+		const result = normalizeInitialSessionOptions({
+			models: { foo: 'bar' },
+		}, logService);
+
+		expect(result).toEqual([]);
+		expect(logService.warn).toHaveBeenCalledWith(expect.stringContaining('Ignoring unsupported initialSessionOptions'));
+	});
+
+	it('logs parse failures when streamed log content is malformed', () => {
+		const logService = new RecordingLogService();
+
+		const result = parseSessionLogChunksSafely('data: {not-json}', logService, () => {
+			throw new SyntaxError('Unexpected token');
+		});
+
+		expect(result).toEqual([]);
+		expect(logService.error).toHaveBeenCalledWith(expect.any(SyntaxError), expect.stringContaining('Failed to parse streamed log content'));
+	});
+});
+
+describe('ChatSessionContentBuilder', () => {
+	it('ignores malformed tool_calls payloads instead of throwing', async () => {
+		const builder = new ChatSessionContentBuilder('copilot-cloud-agent', new TestGitService());
+		const logs = [
+			'data: {"choices":[{"finish_reason":"stop","delta":{"role":"assistant","content":"Cloud reply","tool_calls":{"id":"not-an-array"}}}],"created":0,"id":"chunk-1","usage":{"completion_tokens":0,"prompt_tokens":0,"prompt_tokens_details":{"cached_tokens":0},"total_tokens":0},"model":"test-model","object":"chat.completion.chunk"}',
+		].join('\n');
+
+		const history = await builder.buildSessionHistory(
+			Promise.resolve('Continue in cloud'),
+			[createSession()],
+			createPullRequest(),
+			async () => logs,
+			Promise.resolve([]),
+		);
+
+		expect(history).toHaveLength(2);
+		const responseTurn = history[1];
+		expect(responseTurn).toBeInstanceOf(ChatResponseTurn2);
+		if (!(responseTurn instanceof ChatResponseTurn2)) {
+			throw new Error('Expected a response turn.');
+		}
+
+		expect(responseTurn.response).toHaveLength(1);
+		expect(responseTurn.response[0]).toBeInstanceOf(ChatResponseMarkdownPart);
+		if (!(responseTurn.response[0] instanceof ChatResponseMarkdownPart)) {
+			throw new Error('Expected markdown response content.');
+		}
+
+		expect(responseTurn.response[0].value.value).toBe('Cloud reply');
+	});
+});