Add regression tests for tool-call timeout handling

Extract the shared "race work against a timeout" logic used by
DebuggingExecutor.dapRequest and DebugMCPServer.runTool into a tested
withTimeout() utility (behavior preserved), and add regression coverage
for the "server stuck when a tool call hangs" fix:

- withTimeout.test.ts: resolves fast work, propagates work rejections,
  rejects with the caller's error when work hangs, and clears the timer
  so a late-but-eventual result still wins.
- routing.test.ts: a control server that accepts but never responds must
  cause handleStartDebugging to reject with the actionable "did not
  respond within ... unresponsive" message. RoutingDebuggingHandler now
  accepts an optional forwardTimeoutMs override so the test runs fast.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 6ea24b92-40ad-4539-aa13-61aa6ff8751f

Author: ozzafar

src/debugMCPServer.ts

@@ -11,6 +11,7 @@ import {
     IDebuggingHandler
 } from '.';
 import { logger } from './utils/logger';
+import { withTimeout } from './utils/withTimeout';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
@@ -182,23 +183,15 @@ export class DebugMCPServer {
         toolName: string,
         run: () => Promise<string>
     ): Promise<{ content: { type: 'text'; text: string }[] }> {
-        let timer: ReturnType<typeof setTimeout> | undefined;
-        const backstop = new Promise<never>((_, reject) => {
-            timer = setTimeout(() => {
-                reject(new Error(
-                    `Tool "${toolName}" did not complete within ${Math.round(this.toolBackstopMs / 1000)}s and was aborted. ` +
-                    'The debug adapter or target VS Code window may be unresponsive. Try stop_debugging and retry, or reload the window.'
-                ));
-            }, this.toolBackstopMs);
-        });
-        try {
-            const result = await Promise.race([run(), backstop]);
-            return { content: [{ type: 'text' as const, text: result }] };
-        } finally {
-            if (timer) {
-                clearTimeout(timer);
-            }
-        }
+        const result = await withTimeout(
+            run(),
+            this.toolBackstopMs,
+            () => new Error(
+                `Tool "${toolName}" did not complete within ${Math.round(this.toolBackstopMs / 1000)}s and was aborted. ` +
+                'The debug adapter or target VS Code window may be unresponsive. Try stop_debugging and retry, or reload the window.'
+            )
+        );
+        return { content: [{ type: 'text' as const, text: result }] };
     }
 
     /**

src/debuggingExecutor.ts

@@ -3,6 +3,7 @@
 import * as vscode from 'vscode';
 import { DebugState, StackFrame } from './debugState';
 import { logger } from './utils/logger';
+import { withTimeout } from './utils/withTimeout';
 
 /**
  * Outcome of dispatching `testing.debugAtCursor`.
@@ -62,22 +63,14 @@ export class DebuggingExecutor implements IDebuggingExecutor {
         command: string,
         args: unknown
     ): Promise<any> {
-        let timer: ReturnType<typeof setTimeout> | undefined;
-        const timeout = new Promise<never>((_, reject) => {
-            timer = setTimeout(() => {
-                reject(new Error(
-                    `Debug adapter did not respond to '${command}' within ` +
-                    `${Math.round(DebuggingExecutor.DAP_REQUEST_TIMEOUT_MS / 1000)}s (it may be unresponsive).`
-                ));
-            }, DebuggingExecutor.DAP_REQUEST_TIMEOUT_MS);
-        });
-        try {
-            return await Promise.race([session.customRequest(command, args), timeout]);
-        } finally {
-            if (timer) {
-                clearTimeout(timer);
-            }
-        }
+        return withTimeout(
+            Promise.resolve(session.customRequest(command, args)),
+            DebuggingExecutor.DAP_REQUEST_TIMEOUT_MS,
+            () => new Error(
+                `Debug adapter did not respond to '${command}' within ` +
+                `${Math.round(DebuggingExecutor.DAP_REQUEST_TIMEOUT_MS / 1000)}s (it may be unresponsive).`
+            )
+        );
     }
 
     /**

src/routingDebuggingHandler.ts

@@ -19,14 +19,16 @@ export class RoutingDebuggingHandler implements IDebuggingHandler {
 
 	// Bound the router->worker round-trip so a hung worker can't hang the
 	// forward forever. Kept above the worker's own timeout to avoid preempting
-	// slow-but-progressing operations.
+	// slow-but-progressing operations. `forwardTimeoutMs` can be passed
+	// explicitly (mainly for tests) to override the derived value.
 	private readonly forwardTimeoutMs: number;
 
 	constructor(
 		private readonly registry: WorkspaceRegistry,
-		timeoutInSeconds: number = 180
+		timeoutInSeconds: number = 180,
+		forwardTimeoutMs?: number
 	) {
-		this.forwardTimeoutMs = timeoutInSeconds * 1000 + 15_000;
+		this.forwardTimeoutMs = forwardTimeoutMs ?? timeoutInSeconds * 1000 + 15_000;
 	}
 
 	/**

src/test/routing.test.ts

@@ -2,6 +2,7 @@
 
 import * as assert from 'assert';
 import * as fs from 'fs';
+import * as http from 'http';
 import * as os from 'os';
 import * as path from 'path';
 import { ControlServer } from '../controlServer';
@@ -37,13 +38,15 @@ class RecordingHandler implements IDebuggingHandler {
 suite('Multi-window routing', () => {
 	let dir: string;
 	const servers: ControlServer[] = [];
+	const deadServers: http.Server[] = [];
 
 	setup(() => {
 		dir = fs.mkdtempSync(path.join(os.tmpdir(), 'debugmcp-routing-test-'));
 	});
 
 	teardown(async () => {
 		await Promise.all(servers.splice(0).map(s => s.stop()));
+		await Promise.all(deadServers.splice(0).map(s => new Promise<void>(resolve => s.close(() => resolve()))));
 		fs.rmSync(dir, { recursive: true, force: true });
 	});
 
@@ -143,6 +146,49 @@ suite('Multi-window routing', () => {
 		await assert.rejects(() => routing.handleStepOver(), /no active debug target/i);
 	});
 
+	/**
+	 * Register a window whose control server accepts connections but never
+	 * responds, to simulate a hung/unresponsive VS Code window.
+	 */
+	async function startDeadWindow(fileName: string, workspaceFolders: string[]): Promise<void> {
+		const server = http.createServer(() => { /* accept, never respond */ });
+		deadServers.push(server);
+		const port: number = await new Promise(resolve => {
+			server.listen(0, '127.0.0.1', () => resolve((server.address() as { port: number }).port));
+		});
+		fs.writeFileSync(
+			path.join(dir, fileName),
+			JSON.stringify({
+				pid: process.pid,
+				controlPort: port,
+				controlToken: 'secret',
+				workspaceFolders,
+				name: fileName,
+				updatedAt: Date.now()
+			}),
+			'utf8'
+		);
+	}
+
+	test('rejects with an actionable error when the target window is unresponsive', async () => {
+		const repoA = path.join(dir, 'repoA');
+		await startDeadWindow('a.json', [repoA]);
+
+		// 200ms forward timeout so the hung round-trip fails fast in the test.
+		const routing = new RoutingDebuggingHandler(new WorkspaceRegistry(process.pid, dir), 180, 200);
+		const start = Date.now();
+		await assert.rejects(
+			() => routing.handleStartDebugging({
+				fileFullPath: path.join(repoA, 'm.py'),
+				workingDirectory: repoA
+			}),
+			/did not respond within[\s\S]*unresponsive/i
+		);
+		const elapsed = Date.now() - start;
+		assert.ok(elapsed >= 150, `should wait for the ~200ms forward timeout, only took ${elapsed}ms`);
+		assert.ok(elapsed < 5000, `forward timeout should fire promptly, took ${elapsed}ms`);
+	});
+
 	test('control server rejects requests with a wrong token', async () => {
 		const repoA = path.join(dir, 'repoA');
 		await startWindow('a.json', [repoA], new RecordingHandler('A'), 'right-token');
@@ -160,3 +206,4 @@ suite('Multi-window routing', () => {
 		);
 	});
 });
+

src/test/withTimeout.test.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Microsoft Corporation.
+
+import * as assert from 'assert';
+import { withTimeout } from '../utils/withTimeout';
+
+/**
+ * Regression tests for the shared timeout primitive that bounds every DAP
+ * request (DebuggingExecutor.dapRequest) and every MCP tool call
+ * (DebugMCPServer.runTool). These guard the "server stuck when a tool hangs"
+ * fix: a hung operation must reject with the caller's error instead of
+ * pending forever, and a fast operation must pass through untouched.
+ */
+suite('withTimeout', () => {
+	test('resolves with the work value when it settles in time', async () => {
+		const value = await withTimeout(
+			Promise.resolve('ok'),
+			1000,
+			() => new Error('should not fire')
+		);
+		assert.strictEqual(value, 'ok');
+	});
+
+	test('propagates a rejection from the work promise (not the timeout error)', async () => {
+		await assert.rejects(
+			withTimeout(
+				Promise.reject(new Error('work failed')),
+				1000,
+				() => new Error('timeout error')
+			),
+			/work failed/
+		);
+	});
+
+	test('rejects with the onTimeout error when work never settles', async () => {
+		const start = Date.now();
+		await assert.rejects(
+			withTimeout(
+				new Promise<string>(() => { /* never settles */ }),
+				50,
+				() => new Error('adapter unresponsive')
+			),
+			/adapter unresponsive/
+		);
+		const elapsed = Date.now() - start;
+		assert.ok(elapsed >= 40, `should wait for the ~50ms timeout, only took ${elapsed}ms`);
+		assert.ok(elapsed < 1000, `timeout should fire promptly, took ${elapsed}ms`);
+	});
+
+	test('clears the timer so a late-but-eventual work result still wins', async () => {
+		// Work resolves before the (long) timeout; the timer must be cleared so
+		// it neither delays the result nor rejects afterwards.
+		const work = new Promise<string>(resolve => setTimeout(() => resolve('late-ok'), 20));
+		const value = await withTimeout(work, 5000, () => new Error('should not fire'));
+		assert.strictEqual(value, 'late-ok');
+		// Give any stray timer a chance to (wrongly) fire; nothing should throw.
+		await new Promise(resolve => setTimeout(resolve, 30));
+	});
+});

src/utils/withTimeout.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft Corporation.
+
+/**
+ * Race a promise against a timeout so a hung operation can't block forever.
+ *
+ * Resolves/rejects with `work`'s outcome if it settles within `timeoutMs`;
+ * otherwise rejects with the Error from `onTimeout()`. The timer is always
+ * cleared so a slow-but-eventual `work` doesn't leak a pending timer or a
+ * late rejection. Note: `work` itself is not cancelled — this only bounds how
+ * long the caller waits.
+ */
+export async function withTimeout<T>(
+	work: Promise<T>,
+	timeoutMs: number,
+	onTimeout: () => Error
+): Promise<T> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timeout = new Promise<never>((_, reject) => {
+		timer = setTimeout(() => reject(onTimeout()), timeoutMs);
+	});
+	try {
+		return await Promise.race([work, timeout]);
+	} finally {
+		if (timer) {
+			clearTimeout(timer);
+		}
+	}
+}