Agent Debug: Converge debug data with JSONL as single source of truth (#4954)

* converge debug data

* Feedback updates

* add ver field

* exp update

* subagent fix

* Few fixes and test

* settings update

* msg update

Author: vijayupadya

package.json

@@ -4631,6 +4631,7 @@
 						"type": "boolean",
 						"default": false,
 						"markdownDescription": "%github.copilot.config.chat.agentDebugLog.enabled%",
+						"deprecationMessage": "%github.copilot.config.chat.agentDebugLog.enabled.deprecated%",
 						"tags": [
 							"advanced",
 							"experimental"

package.nls.json

@@ -373,8 +373,9 @@
 	"github.copilot.config.editRecording.enabled": "Enable edit recording for analysis.",
 	"github.copilot.config.inlineChat.selectionRatioThreshold": "Threshold at which to switch editing strategies for inline chat. When a selection portion of code matches a parse tree node, only that is presented to the language model. This speeds up response times but might have lower quality results. Requires having a parse tree for the document and the `inlineChat.enableV2` setting. Values must be between 0 and 1, where 0 means off and 1 means the selection perfectly matches a parse tree node.",
 	"github.copilot.config.debug.requestLogger.maxEntries": "Maximum number of entries to keep in the request logger for debugging purposes.",
-	"github.copilot.config.chat.agentDebugLog.enabled": "When enabled, collect agent request information (tool calls, LLM requests, token usage, and errors) for viewing and troubleshooting in VS Code. Requires window reload to take effect.",
-	"github.copilot.config.chat.agentDebugLog.fileLogging.enabled": "Enable writing chat debug events to JSONL files on disk for diagnostics. When disabled, the built-in `troubleshoot` skill is also disabled. Requires window reload to take effect.",
+	"github.copilot.config.chat.agentDebugLog.enabled": "Deprecated: use `github.copilot.chat.agentDebugLog.fileLogging.enabled` instead.",
+	"github.copilot.config.chat.agentDebugLog.enabled.deprecated": "This setting has been merged into `github.copilot.chat.agentDebugLog.fileLogging.enabled`. Please use this setting instead.",
+	"github.copilot.config.chat.agentDebugLog.fileLogging.enabled": "Enable agent debug logging: write chat debug events (tool calls, LLM requests, token usage, errors) to JSONL files for the debug panel and troubleshoot skill. Requires window reload to take effect.",
 	"github.copilot.config.chat.agentDebugLog.fileLogging.flushIntervalMs": "How often (in milliseconds) buffered debug log entries are flushed to disk. Lower values provide more up-to-date logs at the cost of more frequent disk writes.",
 	"github.copilot.config.chat.agentDebugLog.fileLogging.maxRetainedSessionLogs": "Maximum number of chat debug session log directories to retain on disk. Each chat session produces one directory. Older session logs are automatically deleted when this limit is exceeded.",
 	"github.copilot.config.chat.agentDebugLog.fileLogging.maxSessionLogSizeMB": "Maximum size in megabytes for a single chat debug session log file. When the log exceeds this size, older entries are truncated to retain the most recent data. Defaults to 100 MB.",

src/extension/chat/vscode-node/chatDebugFileLoggerService.ts

@@ -147,7 +147,7 @@ class TestConfigurationService {
 	getConfig(key: { defaultValue: unknown }) { return key.defaultValue; }
 	getExperimentBasedConfig(key: { defaultValue: unknown }) {
 		if (key === ConfigKey.Advanced.ChatDebugFileLogging) {
-			return true; // Enable file logging for tests
+			return true; // Enable debug logging for tests
 		}
 		return key.defaultValue;
 	}
@@ -348,10 +348,11 @@ describe('ChatDebugFileLoggerService', () => {
 		expect(childPath!.fsPath).toContain('parent-session');
 		expect(childPath!.fsPath).toContain('title-title-child-id.jsonl');
 
-		// Child should have the LLM request entry
+		// Child should have the session_start + LLM request entry
 		const childEntries = await readLogEntries('title-child-id');
-		expect(childEntries).toHaveLength(1);
-		expect(childEntries[0].type).toBe('llm_request');
+		expect(childEntries).toHaveLength(2);
+		expect(childEntries[0].type).toBe('session_start');
+		expect(childEntries[1].type).toBe('llm_request');
 	});
 
 	it('restarts flush timer when flushIntervalMs config changes at runtime', async () => {
@@ -522,4 +523,196 @@ describe('ChatDebugFileLoggerService', () => {
 		const content = await fs.promises.readFile(modelsPath, 'utf-8');
 		expect(content).toBe('"sentinel"');
 	});
+
+	it('readEntries returns entries from flushed JSONL and unflushed buffer', async () => {
+		await service.startSession('session-read');
+		otelService.fireSpan(makeToolCallSpan('session-read', 'tool_a'));
+		await service.flush('session-read');
+
+		// Fire another span without flushing — it should be in the buffer
+		otelService.fireSpan(makeToolCallSpan('session-read', 'tool_b'));
+
+		const entries = await service.readEntries('session-read');
+		const toolEntries = entries.filter(e => e.type === 'tool_call');
+		expect(toolEntries.length).toBe(2);
+		expect(toolEntries[0].name).toBe('tool_a');
+		expect(toolEntries[1].name).toBe('tool_b');
+	});
+
+	it('readEntries returns empty array for unknown session', async () => {
+		const entries = await service.readEntries('nonexistent-session');
+		expect(entries).toEqual([]);
+	});
+
+	it('readTailEntries returns last N entries from a flushed session', async () => {
+		await service.startSession('session-tail');
+		for (let i = 0; i < 5; i++) {
+			otelService.fireSpan(makeToolCallSpan('session-tail', `tool_${i}`));
+		}
+		await service.flush('session-tail');
+
+		const entries = await service.readTailEntries('session-tail', 2);
+		const toolEntries = entries.filter(e => e.type === 'tool_call');
+		// Should return the last 2 tool entries
+		expect(toolEntries.length).toBe(2);
+		expect(toolEntries[0].name).toBe('tool_3');
+		expect(toolEntries[1].name).toBe('tool_4');
+	});
+
+	it('streamEntries calls onEntry for each parsed line', async () => {
+		await service.startSession('session-stream');
+		otelService.fireSpan(makeToolCallSpan('session-stream', 'tool_x'));
+		otelService.fireSpan(makeChatSpan('session-stream', 'gpt-4o', 100, 50));
+		await service.flush('session-stream');
+
+		const types: string[] = [];
+		await service.streamEntries('session-stream', entry => {
+			types.push(entry.type);
+		});
+		expect(types).toContain('tool_call');
+		expect(types).toContain('llm_request');
+	});
+
+	it('onDidEmitEntry fires for each buffered entry', async () => {
+		await service.startSession('session-emit');
+		const emitted: Array<{ sessionId: string; type: string }> = [];
+		const sub = service.onDidEmitEntry(({ sessionId, entry }) => {
+			emitted.push({ sessionId, type: entry.type });
+		});
+
+		otelService.fireSpan(makeToolCallSpan('session-emit', 'tool_y'));
+
+		sub.dispose();
+
+		const toolEvents = emitted.filter(e => e.type === 'tool_call');
+		expect(toolEvents.length).toBe(1);
+		expect(toolEvents[0].sessionId).toBe('session-emit');
+	});
+
+	// ── Subagent / child session tests ──
+
+	it('startChildSession with parentToolSpanId sets parentSpanId on child_session_ref', async () => {
+		await service.startSession('parent-1');
+		otelService.fireSpan(makeToolCallSpan('parent-1', 'read_file'));
+
+		service.startChildSession('child-1', 'parent-1', 'runSubagent-Explore', 'tool-span-42');
+
+		// Fire a span for the child to trigger _ensureSession → child_session_ref
+		const childSpan = makeChatSpan('child-1', 'claude-haiku', 100, 20);
+		otelService.fireSpan(childSpan);
+
+		await service.flush('parent-1');
+		await service.flush('child-1');
+
+		const parentEntries = await readLogEntries('parent-1');
+		const ref = parentEntries.find(e => e.type === 'child_session_ref');
+		expect(ref).toBeDefined();
+		expect(ref!.parentSpanId).toBe('tool-span-42');
+		expect((ref!.attrs as Record<string, unknown>).label).toBe('runSubagent-Explore');
+		expect((ref!.attrs as Record<string, unknown>).childSessionId).toBe('child-1');
+	});
+
+	it('startChildSession without parentToolSpanId omits parentSpanId', async () => {
+		await service.startSession('parent-2');
+		otelService.fireSpan(makeToolCallSpan('parent-2', 'read_file'));
+
+		service.startChildSession('child-2', 'parent-2', 'title');
+
+		const childSpan = makeChatSpan('child-2', 'gpt-4o-mini', 50, 10);
+		otelService.fireSpan(childSpan);
+
+		await service.flush('parent-2');
+		await service.flush('child-2');
+
+		const parentEntries = await readLogEntries('parent-2');
+		const ref = parentEntries.find(e => e.type === 'child_session_ref');
+		expect(ref).toBeDefined();
+		expect(ref!.parentSpanId).toBeUndefined();
+	});
+
+	it('child session JSONL is written under parent directory', async () => {
+		await service.startSession('parent-dir');
+		otelService.fireSpan(makeToolCallSpan('parent-dir', 'read_file'));
+
+		service.startChildSession('child-dir', 'parent-dir', 'runSubagent-default', 'tool-span-1');
+
+		otelService.fireSpan(makeChatSpan('child-dir', 'claude-opus', 500, 100));
+
+		await service.flush('parent-dir');
+		await service.flush('child-dir');
+
+		const childLogPath = service.getLogPath('child-dir');
+		expect(childLogPath).toBeDefined();
+		expect(childLogPath!.fsPath).toContain('parent-dir');
+		expect(childLogPath!.fsPath).toContain('runSubagent-default-child-dir.jsonl');
+	});
+
+	it('child_session_ref includes childLogFile for direct file read fallback', async () => {
+		await service.startSession('parent-file');
+		otelService.fireSpan(makeToolCallSpan('parent-file', 'read_file'));
+
+		service.startChildSession('child-file', 'parent-file', 'runSubagent-Explore', 'tool-span-2');
+
+		otelService.fireSpan(makeChatSpan('child-file', 'claude-haiku', 100, 20));
+
+		await service.flush('parent-file');
+		await service.flush('child-file');
+
+		const parentEntries = await readLogEntries('parent-file');
+		const ref = parentEntries.find(e => e.type === 'child_session_ref');
+		expect(ref).toBeDefined();
+		expect((ref!.attrs as Record<string, unknown>).childLogFile).toBe('runSubagent-Explore-child-file.jsonl');
+		expect((ref!.attrs as Record<string, unknown>).childSessionId).toBe('child-file');
+	});
+
+	it('readEntries returns child session entries', async () => {
+		await service.startSession('parent-read');
+		otelService.fireSpan(makeToolCallSpan('parent-read', 'read_file'));
+
+		service.startChildSession('child-read', 'parent-read', 'runSubagent-default');
+
+		otelService.fireSpan(makeToolCallSpan('child-read', 'file_search'));
+		otelService.fireSpan(makeChatSpan('child-read', 'claude-haiku', 200, 50));
+
+		await service.flush('parent-read');
+		await service.flush('child-read');
+
+		const childEntries = await service.readEntries('child-read');
+		const types = childEntries.map(e => e.type);
+		expect(types).toContain('session_start');
+		expect(types).toContain('tool_call');
+		expect(types).toContain('llm_request');
+		expect(childEntries.length).toBe(3);
+	});
+
+	it('multiple child sessions under same parent each get their own file', async () => {
+		await service.startSession('parent-multi');
+		otelService.fireSpan(makeToolCallSpan('parent-multi', 'read_file'));
+
+		service.startChildSession('child-a', 'parent-multi', 'runSubagent-Explore', 'tool-a');
+		service.startChildSession('child-b', 'parent-multi', 'runSubagent-default', 'tool-b');
+
+		otelService.fireSpan(makeChatSpan('child-a', 'claude-haiku', 100, 20));
+		otelService.fireSpan(makeChatSpan('child-b', 'claude-haiku', 150, 30));
+
+		await service.flush('parent-multi');
+		await service.flush('child-a');
+		await service.flush('child-b');
+
+		// Parent should have two child_session_ref entries
+		const parentEntries = await readLogEntries('parent-multi');
+		const refs = parentEntries.filter(e => e.type === 'child_session_ref');
+		expect(refs).toHaveLength(2);
+
+		const labels = refs.map(r => (r.attrs as Record<string, unknown>).label);
+		expect(labels).toContain('runSubagent-Explore');
+		expect(labels).toContain('runSubagent-default');
+
+		// Each child has its own log path
+		const pathA = service.getLogPath('child-a');
+		const pathB = service.getLogPath('child-b');
+		expect(pathA).toBeDefined();
+		expect(pathB).toBeDefined();
+		expect(pathA!.fsPath).not.toBe(pathB!.fsPath);
+	});
 });

src/extension/chat/vscode-node/test/chatDebugFileLoggerService.spec.ts

@@ -7,6 +7,7 @@ import * as l10n from '@vscode/l10n';
 import { Raw } from '@vscode/prompt-tsx';
 import type { CancellationToken, ChatRequest, ChatResponseProgressPart, ChatResponseReferencePart, ChatResponseStream, ChatResult, LanguageModelToolInformation, Progress } from 'vscode';
 import { IAuthenticationChatUpgradeService } from '../../../platform/authentication/common/authenticationUpgrade';
+import { IChatDebugFileLoggerService } from '../../../platform/chat/common/chatDebugFileLoggerService';
 import { IChatHookService, SessionStartHookInput, SessionStartHookOutput, StopHookInput, StopHookOutput, SubagentStartHookInput, SubagentStartHookOutput, SubagentStopHookInput, SubagentStopHookOutput } from '../../../platform/chat/common/chatHookService';
 import { FetchStreamSource, IResponsePart } from '../../../platform/chat/common/chatMLFetcher';
 import { CanceledResult, ChatFetchResponseType, ChatResponse } from '../../../platform/chat/common/commonTypes';
@@ -727,6 +728,8 @@ export abstract class ToolCallingLoop<TOptions extends IToolCallingLoopOptions =
 
 		// Get the VS Code chat session ID from the CapturingToken (same mechanism as old debug panel)
 		const chatSessionId = getCurrentCapturingToken()?.chatSessionId;
+		const parentChatSessionId = getCurrentCapturingToken()?.parentChatSessionId;
+		const debugLogLabel = getCurrentCapturingToken()?.debugLogLabel;
 
 		return this._otelService.startActiveSpan(
 			`invoke_agent ${agentName}`,
@@ -739,6 +742,8 @@ export abstract class ToolCallingLoop<TOptions extends IToolCallingLoopOptions =
 					[GenAiAttr.CONVERSATION_ID]: this.options.conversation.sessionId,
 					[CopilotChatAttr.SESSION_ID]: this.options.conversation.sessionId,
 					...(chatSessionId ? { [CopilotChatAttr.CHAT_SESSION_ID]: chatSessionId } : {}),
+					...(parentChatSessionId ? { [CopilotChatAttr.PARENT_CHAT_SESSION_ID]: parentChatSessionId } : {}),
+					...(debugLogLabel ? { [CopilotChatAttr.DEBUG_LOG_LABEL]: debugLogLabel } : {}),
 					...(customModeName ? { 'copilot_chat.mode_name': customModeName } : {}),
 					...workspaceMetadataToOTelAttributes(resolveWorkspaceOTelMetadata(this._gitService)),
 				},
@@ -747,6 +752,17 @@ export abstract class ToolCallingLoop<TOptions extends IToolCallingLoopOptions =
 			async (span) => {
 				const otelStartTime = Date.now();
 
+				// Register this session as a child of its parent so that debug
+				// log entries are routed to a dedicated child JSONL file.
+				// parentChatSessionId is only set on subagent requests
+				// (see CapturingToken setup in defaultIntentRequestHandler).
+				if (parentChatSessionId && chatSessionId) {
+					const childLabel = debugLogLabel ?? `runSubagent-${agentName}`;
+					this._instantiationService.invokeFunction(accessor =>
+						accessor.get(IChatDebugFileLoggerService).startChildSession(
+							chatSessionId, parentChatSessionId, childLabel, parentTraceContext?.spanId));
+				}
+
 				// Emit session start event and metric for top-level agent invocations (not subagents)
 				if (!parentTraceContext) {
 					GenAiMetrics.incrementSessionCount(this._otelService);

src/extension/intents/node/toolCallingLoop.ts

@@ -123,6 +123,8 @@ export class ToolsService extends BaseToolsService {
 		const isMcpTool = String(name).includes('mcp_');
 		const toolInfo = this.tools.find(t => t.name === String(name));
 		const chatSessionId = getCurrentCapturingToken()?.chatSessionId;
+		const parentChatSessionId = getCurrentCapturingToken()?.parentChatSessionId;
+		const debugLogLabel = getCurrentCapturingToken()?.debugLogLabel;
 		const parentTraceContext = (options as { parentTraceContext?: { traceId: string; spanId: string } }).parentTraceContext;
 		const span = this._otelService.startSpan(`execute_tool ${name}`, {
 			kind: SpanKind.INTERNAL,
@@ -134,6 +136,8 @@ export class ToolsService extends BaseToolsService {
 				[GenAiAttr.TOOL_CALL_ID]: (options as { chatStreamToolCallId?: string }).chatStreamToolCallId ?? '',
 				...(toolInfo?.description ? { [GenAiAttr.TOOL_DESCRIPTION]: toolInfo.description } : {}),
 				...(chatSessionId ? { [CopilotChatAttr.CHAT_SESSION_ID]: chatSessionId } : {}),
+				...(parentChatSessionId ? { [CopilotChatAttr.PARENT_CHAT_SESSION_ID]: parentChatSessionId } : {}),
+				...(debugLogLabel ? { [CopilotChatAttr.DEBUG_LOG_LABEL]: debugLogLabel } : {}),
 			},
 		});
 		// Always capture tool call arguments for the debug panel