Skip to content

Chrome DevTools for coding agents

fix: preserve task serialization on request cancellation (#3079)

lisa031403fd4e840c6a
diff --git a/src/BUILD.gn b/src/BUILD.gn
index b846c17a..9f2464cd 100644
--- a/src/BUILD.gn
+++ b/src/BUILD.gn
@@ -153,6 +153,7 @@ ts_library("mcp_lib") {
"utils/logger.ts",
"utils/pagination.ts",
"utils/polyfill.ts",
+ "utils/raceWithSignal.ts",
"utils/resourceType.ts",
"utils/text.ts",
"utils/timeout.ts",
diff --git a/src/ToolHandler.ts b/src/ToolHandler.ts
index ead3fa13..52954e90 100644
--- a/src/ToolHandler.ts
+++ b/src/ToolHandler.ts
@@ -12,6 +12,7 @@ import {McpResponse, type DataFormat} from './McpResponse.js';
import {SlimMcpResponse} from './SlimMcpResponse.js';
import {ClearcutLogger} from './telemetry/ClearcutLogger.js';
import {
+ DisposableStack,
ProtocolError,
ProtocolErrorCode,
zod,
@@ -34,6 +35,7 @@ import {
} from './tools/ToolDefinition.js';
import {getErrorMessage, toError} from './utils/errorHandling.js';
import {logger} from './utils/logger.js';
+import {raceWithSignal} from './utils/raceWithSignal.js';
import type {TaskQueue} from './utils/TaskRunner.js';
import {fileURLToPath, pathToFileURL} from 'node:url';
import {isDeepStrictEqual} from 'node:util';
@@ -312,14 +314,16 @@ export class ToolHandler {
}
/**
- * Races a promise against TOOL_CALL_TIMEOUT_MS, calling onTimeout() if the
- * timer wins. The loser of the race is left running — there is no way to
+ * Races a promise against TOOL_CALL_TIMEOUT_MS and signal abort, calling
+ * onTimeout() only if the timer wins, never on abort.
+ * The loser of the race is left running — there is no way to
* cancel a pending connect/launch — but since nothing is left awaiting it,
* it cannot block subsequent tool calls.
*/
async #raceWithTimeout<T>(
promise: Promise<T>,
onTimeout: () => void,
+ signal: AbortSignal,
): Promise<T> {
const timeoutError = new ToolCallTimeoutError(
`Tool "${this.#tool.name}" timed out after ${TOOL_CALL_TIMEOUT_MS}ms waiting for the browser connection to be established. The connection attempt will be retried automatically on the next tool call.`,
@@ -330,7 +334,7 @@ export class ToolHandler {
timer.unref?.();
});
try {
- return await Promise.race([promise, timeout]);
+ return await raceWithSignal(Promise.race([promise, timeout]), signal);
} catch (err) {
if (err === timeoutError) {
onTimeout();
@@ -359,13 +363,17 @@ export class ToolHandler {
params: Record<string, unknown>,
response: McpResponse,
context: McpContext,
+ signal: AbortSignal,
): ReturnType<McpResponse['handle']> {
try {
await validateToolFiles(tool, params, context, true);
+ signal.throwIfAborted();
await tool.handler({params}, response, context);
} catch (err) {
+ signal.throwIfAborted();
response.setError(toError(err));
}
+ signal.throwIfAborted();
return await response.handle(
context,
this.#dataFormat(this.#config.resolved),
@@ -377,6 +385,7 @@ export class ToolHandler {
params: Record<string, unknown>,
response: McpResponse,
context: McpContext,
+ signal: AbortSignal,
onTelemetryData: (
devToolsData: DevToolsData | undefined,
pageUrl: string | undefined,
@@ -388,8 +397,10 @@ export class ToolHandler {
// discard that attempt if it succeeds later instead of handing it to a
// subsequent caller — see BrowserManager#abandonPendingAttempt()'s doc
// comment for the full mechanism.
- const browser = await this.#raceWithTimeout(context.ensureBrowser(), () =>
- this.abandonPendingBrowserAttemptOnTimeout(),
+ const browser = await this.#raceWithTimeout(
+ context.ensureBrowser(),
+ () => this.abandonPendingBrowserAttemptOnTimeout(),
+ signal,
);
logger?.(`${tool.name} browser: resolved`);
if (context.consumeReconnectNotice()) {
@@ -398,6 +409,7 @@ export class ToolHandler {
let page: McpPage | undefined;
try {
await validateToolFiles(tool, params, context, isLocalBrowser(browser));
+ signal.throwIfAborted();
if (isPageScopedTool(tool)) {
const pageId = routedPageId(tool, this.#config.resolved, params);
page =
@@ -405,6 +417,7 @@ export class ToolHandler {
? context.getPageById(pageId)
: context.getSelectedMcpPage();
await page?.init({emulateFocus: true});
+ signal.throwIfAborted();
response.setPage(page);
if (tool.blockedByDialog) {
page.throwIfDialogOpen();
@@ -427,12 +440,13 @@ export class ToolHandler {
);
}
} catch (err) {
+ signal.throwIfAborted();
response.setError(toError(err));
}
- onTelemetryData(
- await context.getDevToolsData(page),
- context.getSelectedMcpPageUrl(page),
- );
+ signal.throwIfAborted();
+ const devToolsData = await context.getDevToolsData(page);
+ signal.throwIfAborted();
+ onTelemetryData(devToolsData, context.getSelectedMcpPageUrl(page));
return await response.handle(
context,
this.#dataFormat(this.#config.resolved),
@@ -464,19 +478,29 @@ export class ToolHandler {
}
}
- handle = async (
+ /**
+ * Cancellation stops waiting for a result, but running work keeps its queue
+ * until it settles, including response processing, to preserve serialization.
+ * Operations without cancellation support can keep the queue indefinitely.
+ */
+ async handle(
rawArgs: Record<string, unknown> = {},
- options?: {viaMcp?: boolean},
- ): Promise<CallToolResult> => {
- const context = await this.getContext();
+ options?: {viaMcp?: boolean; signal?: AbortSignal},
+ ): Promise<CallToolResult> {
+ const signal = options?.signal ?? new AbortController().signal;
+ signal.throwIfAborted();
+ const context = await raceWithSignal(this.getContext(), signal);
let queueGuard: Disposable | undefined;
try {
- queueGuard = await this.#queueFor(context, rawArgs)?.scheduleTask();
+ queueGuard = await this.#queueFor(context, rawArgs)?.scheduleTask(signal);
} catch (err) {
+ signal.throwIfAborted();
// The queue was disposed while the call waited, e.g. the page closed.
return errorResult(getErrorMessage(err));
}
- using guard = queueGuard;
+ using guard = new DisposableStack();
+ guard.use(queueGuard);
+ signal.throwIfAborted();
if (options?.viaMcp && this.#disabled) {
throw new ProtocolError(
ProtocolErrorCode.InvalidParams,
@@ -504,18 +528,26 @@ export class ToolHandler {
const response = isSlimTool(tool)
? new SlimMcpResponse(this.#config)
: new McpResponse(this.#config);
- const {content, structuredContent} = isBrowserlessTool(tool)
- ? await this.#runBrowserlessTool(tool, params, response, context)
- : await this.#runBrowserTool(
+ // The execution owns the queue even when its caller stops waiting.
+ const execution = isBrowserlessTool(tool)
+ ? this.#runBrowserlessTool(tool, params, response, context, signal)
+ : this.#runBrowserTool(
tool,
params,
response,
context,
+ signal,
(data, url) => {
devToolsData = data;
pageUrl = url;
},
);
+ const executionGuard = guard.move();
+ const completion = execution.finally(() => executionGuard.dispose());
+ const {content, structuredContent} = await raceWithSignal(
+ completion,
+ signal,
+ );
const result: CallToolResult & {
structuredContent?: Record<string, unknown>;
} = {
@@ -530,6 +562,10 @@ export class ToolHandler {
}
return result;
} catch (err) {
+ if (signal.aborted) {
+ logger?.(`${tool.name} cancelled:`, signal.reason);
+ }
+ signal.throwIfAborted();
logger?.(`${tool.name} error:`, err, err?.stack);
let errorText =
err && typeof err === 'object' && 'message' in err
@@ -563,5 +599,5 @@ export class ToolHandler {
pageUrl,
});
}
- };
+ }
}
diff --git a/src/index.ts b/src/index.ts
index f8a96c75..b30adb75 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -397,7 +397,7 @@ export class McpServer {
* checks run inside `ToolHandler.handle()` inside the task runner.
*/
#setToolCallRequestHandler(): void {
- this.server.server.setRequestHandler('tools/call', async request => {
+ this.server.server.setRequestHandler('tools/call', async (request, ctx) => {
const entry = this.#tools.get(request.params.name);
if (!entry) {
throw new ProtocolError(
@@ -407,6 +407,7 @@ export class McpServer {
}
const result = await entry.handler.handle(request.params.arguments, {
viaMcp: true,
+ signal: ctx.mcpReq.signal,
});
return this.server.server.projectCallToolResult(result, undefined);
});
diff --git a/src/tools/input.ts b/src/tools/input.ts
index 91cfb2c9..d6e4e4cb 100644
--- a/src/tools/input.ts
+++ b/src/tools/input.ts
@@ -13,6 +13,7 @@ import {
import type {TextSnapshotNode} from '../types.js';
import {parseKey, throwIfInvalidKey} from '../utils/keyboard.js';
import {logger} from '../utils/logger.js';
+import {raceWithSignal} from '../utils/raceWithSignal.js';
import type {WaitForEventsResult} from '../utils/WaitForHelper.js';
import {ToolCategory} from './categories.js';
@@ -256,31 +257,6 @@ export const hover: PageToolFactory = definePageTool(() => ({
},
}));
-function raceWithSignal<T>(
- promise: Promise<T>,
- signal: AbortSignal,
-): Promise<T> {
- if (signal.aborted) {
- return Promise.reject(signal.reason);
- }
- return new Promise<T>((resolve, reject) => {
- const onAbort = (): void => {
- reject(signal.reason);
- };
- signal.addEventListener('abort', onAbort, {once: true});
- Promise.resolve(promise).then(
- value => {
- signal.removeEventListener('abort', onAbort);
- resolve(value);
- },
- error => {
- signal.removeEventListener('abort', onAbort);
- reject(error);
- },
- );
- });
-}
-
// The AXNode for an option doesn't contain its `value`. We set text content of the option as value.
// If the form is a combobox, we need to find the correct option by its text value.
// To do that, loop through the children while checking which child's text matches the requested value (requested value is actually the text content).
diff --git a/src/utils/TaskRunner.ts b/src/utils/TaskRunner.ts
index e523e2a9..92ca23ba 100644
--- a/src/utils/TaskRunner.ts
+++ b/src/utils/TaskRunner.ts
@@ -11,12 +11,12 @@ interface Entry {
priority: Priority;
running: boolean;
resolve: () => void;
- reject: (error: Error) => void;
+ reject: (reason: unknown) => void;
}
/** The runner methods a queue uses. Not part of the public API. */
interface QueueHooks {
- scheduleTask(queue: TaskQueue): Promise<Disposable>;
+ scheduleTask(queue: TaskQueue, signal?: AbortSignal): Promise<Disposable>;
cancel(queue: TaskQueue, reason: Error): void;
}
@@ -39,13 +39,14 @@ export class TaskQueue {
* Schedules a task on this queue. Resolves when no earlier task on a
* related queue runs, with a guard that holds the queue until it is
* disposed. Rejects when the queue is disposed while the task waits. A
- * second dispose of the guard throws.
+ * second dispose of the guard throws. Cancellation rejects a waiting task
+ * with the signal's reason; after acquisition, the caller owns the guard.
*/
- async scheduleTask(): Promise<Disposable> {
+ async scheduleTask(signal?: AbortSignal): Promise<Disposable> {
if (this.#disposed) {
throw this.#disposed;
}
- return await this.#hooks.scheduleTask(this);
+ return await this.#hooks.scheduleTask(this, signal);
}
/**
@@ -85,7 +86,8 @@ export class TaskQueue {
*/
export class TaskRunner {
readonly #hooks: QueueHooks = {
- scheduleTask: queue => this.#scheduleTask(queue),
+ scheduleTask: (queue, signal) =>
+ this.#scheduleTask(queue, 'normal', signal),
cancel: (queue, reason) => this.#cancel(queue, reason),
};
readonly #root = new TaskQueue(this.#hooks, undefined);
@@ -112,25 +114,44 @@ export class TaskRunner {
async #scheduleTask(
queue: TaskQueue,
priority: Priority = 'normal',
+ signal?: AbortSignal,
): Promise<Disposable> {
- const {guard, started} = this.#enter(queue, priority);
- await started;
- return guard;
+ signal?.throwIfAborted();
+ const {entry, started} = this.#enter(queue, priority);
+ const onAbort = (): void => {
+ this.#cancelEntry(entry, signal?.reason);
+ };
+ signal?.addEventListener('abort', onAbort, {once: true});
+ try {
+ await started;
+ return {
+ [Symbol.dispose]: () => this.#leave(entry),
+ };
+ } finally {
+ signal?.removeEventListener('abort', onAbort);
+ }
}
#cancel(queue: TaskQueue, reason: Error): void {
for (const entry of [...this.#entries]) {
- if (entry.queue === queue && !entry.running) {
- this.#leave(entry);
- entry.reject(reason);
+ if (entry.queue === queue) {
+ this.#cancelEntry(entry, reason);
}
}
}
+ #cancelEntry(entry: Entry, reason: unknown): void {
+ if (entry.running || !this.#entries.includes(entry)) {
+ return;
+ }
+ this.#leave(entry);
+ entry.reject(reason);
+ }
+
#enter(
queue: TaskQueue,
priority: Priority,
- ): {guard: Disposable; started: Promise<void>} {
+ ): {entry: Entry; started: Promise<void>} {
const {promise, resolve, reject} = Promise.withResolvers<void>();
const entry: Entry = {queue, priority, running: false, resolve, reject};
// A high-priority entry goes before the first waiting normal entry.
@@ -142,11 +163,7 @@ export class TaskRunner {
this.#schedule();
return {
started: promise,
- guard: {
- [Symbol.dispose]: () => {
- this.#leave(entry);
- },
- },
+ entry,
};
}
diff --git a/src/utils/raceWithSignal.ts b/src/utils/raceWithSignal.ts
new file mode 100644
index 00000000..19521323
--- /dev/null
+++ b/src/utils/raceWithSignal.ts
@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export function raceWithSignal<T>(
+ promise: Promise<T>,
+ signal: AbortSignal,
+): Promise<T> {
+ return new Promise<T>((resolve, reject) => {
+ const onAbort = (): void => {
+ reject(signal.reason);
+ };
+ if (signal.aborted) {
+ onAbort();
+ } else {
+ signal.addEventListener('abort', onAbort, {once: true});
+ }
+ Promise.resolve(promise).then(
+ value => {
+ signal.removeEventListener('abort', onAbort);
+ resolve(value);
+ },
+ error => {
+ signal.removeEventListener('abort', onAbort);
+ reject(error);
+ },
+ );
+ });
+}
diff --git a/tests/BUILD.gn b/tests/BUILD.gn
index 522ffeba..c9e6cc03 100644
--- a/tests/BUILD.gn
+++ b/tests/BUILD.gn
@@ -115,6 +115,7 @@ ts_library("tests") {
"utils/keyboard.test.ts",
"utils/logger.test.ts",
"utils/pagination.test.ts",
+ "utils/raceWithSignal.test.ts",
"utils/resourceType.test.ts",
"utils/text.test.ts",
"utils/timeout.test.ts",
diff --git a/tests/McpServer.test.ts b/tests/McpServer.test.ts
index 6fd34371..95444546 100644
--- a/tests/McpServer.test.ts
+++ b/tests/McpServer.test.ts
@@ -22,6 +22,7 @@ import {mcpOptions} from '../src/config/mcp-options.js';
import {McpServer} from '../src/index.js';
import {McpContext} from '../src/McpContext.js';
import {ClearcutLogger} from '../src/telemetry/ClearcutLogger.js';
+import {ToolHandler} from '../src/ToolHandler.js';
import type {ToolCategory} from '../src/tools/categories.js';
import type {ToolDefinition} from '../src/tools/ToolDefinition.js';
import {saveLogsToFile} from '../src/utils/logger.js';
@@ -116,6 +117,43 @@ describe('McpServer', () => {
});
describe('callTool', () => {
+ it('forwards the MCP request signal through the dispatcher', async () => {
+ const started = Promise.withResolvers<AbortSignal>();
+ const aborted = Promise.withResolvers<void>();
+ const handle = sinon
+ .stub(ToolHandler.prototype, 'handle')
+ .callsFake(async (_args, options) => {
+ const signal = options?.signal;
+ assert.ok(signal);
+ signal.addEventListener('abort', () => aborted.resolve(), {
+ once: true,
+ });
+ started.resolve(signal);
+ await aborted.promise;
+ signal.throwIfAborted();
+ return {content: []};
+ });
+ const {server} = await createTestServer();
+ const client = await connectClient(server);
+ try {
+ const controller = new AbortController();
+ const pending = client.callTool(
+ {name: 'list_pages', arguments: {}},
+ {signal: controller.signal},
+ );
+ const signal = await started.promise;
+ sinon.assert.calledOnceWithExactly(handle, {}, {viaMcp: true, signal});
+ assert.strictEqual(signal.aborted, false);
+ controller.abort();
+ await assert.rejects(pending);
+ await aborted.promise;
+ assert.strictEqual(signal.aborted, true);
+ } finally {
+ await client.close();
+ await server.close();
+ }
+ });
+
it('returns an error for unknown tool names', async () => {
const {server, browserManager} = await createTestServer();
diff --git a/tests/ToolHandler.test.ts b/tests/ToolHandler.test.ts
index 96430e0d..047ba68a 100644
--- a/tests/ToolHandler.test.ts
+++ b/tests/ToolHandler.test.ts
@@ -6,6 +6,7 @@
import assert from 'node:assert';
import {ChildProcess} from 'node:child_process';
+import {getEventListeners} from 'node:events';
import path from 'node:path';
import {afterEach, describe, it} from 'node:test';
import {pathToFileURL} from 'node:url';
@@ -38,13 +39,15 @@ import {
type DefinedPageTool,
type DevToolsData,
type ToolDefinition,
+ type ToolConcurrency,
} from '../src/tools/ToolDefinition.js';
import {evaluateScript} from '../src/tools/script.js';
import {mockNetwork} from '../src/tools/network.js';
+import {selectPage} from '../src/tools/pages.js';
import {createTools} from '../src/tools/tools.js';
import {TaskRunner, type TaskQueue} from '../src/utils/TaskRunner.js';
import {createMockMcpContext, createMockMcpPage} from './mocks.js';
-import {getMockBrowser, withMcpContext} from './utils.js';
+import {getMockBrowser, settle, withMcpContext} from './utils.js';
describe('ToolHandler', () => {
/** Runs `fn` as a task on `queue`. */
@@ -110,6 +113,438 @@ describe('ToolHandler', () => {
assert.strictEqual(handlerCalled, true);
});
+ describe('cancellation', () => {
+ const modes: Array<ToolConcurrency | 'browserless'> = [
+ 'exclusive',
+ 'page',
+ 'none',
+ 'browserless',
+ ];
+ for (const mode of modes) {
+ for (const rejects of [false, true]) {
+ const outcome = rejects ? 'failure' : 'completion';
+ it(`logs abort and retains running queues until late ${outcome} (${mode})`, async () => {
+ const started = Promise.withResolvers<void>();
+ const execution = Promise.withResolvers<void>();
+ const config = parseConfig();
+ const definition = {
+ name: 'cancelled_tool',
+ description: 'A tool awaiting an external operation',
+ annotations: {category: ToolCategory.INPUT, readOnlyHint: false},
+ schema: {},
+ blockedByDialog: false,
+ verifyFilesSchema: {},
+ handler: async () => {
+ started.resolve();
+ await execution.promise;
+ },
+ } satisfies Omit<
+ BrowserlessToolDefinition,
+ 'browserless' | 'concurrency'
+ >;
+ const tool =
+ mode === 'browserless'
+ ? defineBrowserlessTool(() => definition)(config.resolved)
+ : definePageTool(() => ({...definition, concurrency: mode}))(
+ config.resolved,
+ );
+ const runner = new TaskRunner();
+ const page = createMockMcpPage();
+ const context = createMockMcpContext({taskRunner: runner});
+ context.ensureBrowser.resolves(getMockBrowser());
+ context.getPageById.returns(page);
+ const queue =
+ mode === 'page' ? context.pageTaskQueue(1) : context.taskQueue;
+ const schedule = sinon.spy(queue, 'scheduleTask');
+ const responseHandle = sinon
+ .stub(McpResponse.prototype, 'handle')
+ .resolves({content: [], structuredContent: {}});
+ const responseError = sinon.spy(McpResponse.prototype, 'setError');
+ const telemetry = sinon.createStubInstance(ClearcutLogger);
+ sinon.stub(ClearcutLogger, 'get').returns(telemetry);
+ sinon.stub(Date, 'now').returns(1_000);
+ const abandonBrowser = sinon.spy();
+ const controller = new AbortController();
+ const handler = new ToolHandler(
+ tool,
+ config,
+ async () => context,
+ abandonBrowser,
+ );
+ const args = mode === 'browserless' ? {} : {pageId: 1};
+ const pending = handler.handle(args, {signal: controller.signal});
+ await started.promise;
+ if (mode === 'none' || mode === 'browserless') {
+ sinon.assert.notCalled(schedule);
+ } else {
+ sinon.assert.calledOnceWithExactly(schedule, controller.signal);
+ }
+ controller.abort();
+ await assert.rejects(pending, {name: 'AbortError'});
+ const invocation = {
+ toolName: tool.name,
+ params: args,
+ schema: tool.schema,
+ success: false,
+ latencyMs: 0,
+ devToolsData: undefined,
+ pageUrl: undefined,
+ };
+ sinon.assert.calledOnceWithExactly(
+ telemetry.logToolInvocation,
+ invocation,
+ );
+ assert.deepStrictEqual(
+ getEventListeners(controller.signal, 'abort'),
+ [],
+ );
+ const acquired = sinon.spy();
+ const probe = queue.scheduleTask().then(guard => {
+ acquired();
+ return guard;
+ });
+ await settle();
+ if (mode === 'exclusive' || mode === 'page') {
+ sinon.assert.notCalled(acquired);
+ } else {
+ sinon.assert.calledOnceWithExactly(acquired);
+ }
+ if (mode === 'page') {
+ using unrelated = await context.pageTaskQueue(2).scheduleTask();
+ }
+
+ if (rejects) {
+ execution.reject(new Error('late failure'));
+ } else {
+ execution.resolve();
+ }
+ (await probe)[Symbol.dispose]();
+ await settle();
+ sinon.assert.calledOnceWithExactly(acquired);
+ sinon.assert.notCalled(responseHandle);
+ sinon.assert.notCalled(responseError);
+ sinon.assert.notCalled(context.getDevToolsData);
+ sinon.assert.calledOnceWithExactly(
+ telemetry.logToolInvocation,
+ invocation,
+ );
+ sinon.assert.notCalled(abandonBrowser);
+ const lateProbe = await queue.scheduleTask();
+ lateProbe[Symbol.dispose]();
+ const pause = await runner.pause();
+ pause[Symbol.dispose]();
+
+ const nextRun = sinon.stub().resolves();
+ const nextHandler = new ToolHandler(
+ {...tool, name: 'next_tool', handler: nextRun},
+ config,
+ async () => context,
+ abandonBrowser,
+ );
+ assert.strictEqual(
+ (await nextHandler.handle(args)).isError,
+ undefined,
+ );
+ sinon.assert.calledOnceWithExactly(
+ nextRun,
+ mode === 'browserless' ? {params: args} : {params: args, page},
+ responseHandle.firstCall.thisValue,
+ context,
+ );
+ });
+ }
+ }
+
+ for (const concurrency of [
+ 'exclusive',
+ 'page',
+ ] satisfies ToolConcurrency[]) {
+ it(`cancels a queued ${concurrency} tool`, async () => {
+ const config = parseConfig();
+ const run = sinon.stub().resolves();
+ const tool = definePageTool(() => ({
+ name: 'queued_tool',
+ description: 'A queued tool',
+ annotations: {category: ToolCategory.INPUT, readOnlyHint: true},
+ schema: {},
+ blockedByDialog: false,
+ concurrency,
+ verifyFilesSchema: {},
+ handler: run,
+ }))(config.resolved);
+ const context = createMockMcpContext();
+ const queue =
+ concurrency === 'page' ? context.pageTaskQueue(1) : context.taskQueue;
+ const holder = await queue.scheduleTask();
+ const controller = new AbortController();
+ const handler = new ToolHandler(
+ tool,
+ config,
+ async () => context,
+ sinon.spy(),
+ );
+ const pending = handler.handle(
+ {pageId: 1},
+ {signal: controller.signal},
+ );
+ await settle();
+ controller.abort();
+ await assert.rejects(pending, {name: 'AbortError'});
+ holder[Symbol.dispose]();
+ using probe = await queue.scheduleTask();
+ sinon.assert.notCalled(context.ensureBrowser);
+ sinon.assert.notCalled(run);
+ assert.deepStrictEqual(
+ getEventListeners(controller.signal, 'abort'),
+ [],
+ );
+ });
+ }
+
+ it('releases a guard acquired just before cancellation', async () => {
+ const config = parseConfig();
+ const context = createMockMcpContext();
+ const controller = new AbortController();
+ const scheduleTask = context.taskQueue.scheduleTask.bind(
+ context.taskQueue,
+ );
+ sinon.stub(context.taskQueue, 'scheduleTask').callsFake(async signal => {
+ const guard = await scheduleTask(signal);
+ controller.abort();
+ return guard;
+ });
+ const handler = new ToolHandler(
+ evaluateScript(config.resolved),
+ config,
+ async () => context,
+ sinon.spy(),
+ );
+ await assert.rejects(handler.handle({}, {signal: controller.signal}), {
+ name: 'AbortError',
+ });
+ using probe = await scheduleTask();
+ sinon.assert.notCalled(context.ensureBrowser);
+ assert.deepStrictEqual(getEventListeners(controller.signal, 'abort'), []);
+ });
+
+ for (const stage of ['context', 'browser', 'page', 'files', 'telemetry']) {
+ it(`skips work after ${stage} cancellation`, async () => {
+ const started = Promise.withResolvers<void>();
+ const initialization = Promise.withResolvers<void>();
+ const config = parseConfig(['--no-page-id-routing']);
+ const run = sinon.stub().resolves();
+ const tool = definePageTool(() => ({
+ name: 'page_tool',
+ description: 'A page tool',
+ annotations: {category: ToolCategory.INPUT, readOnlyHint: true},
+ schema: {file: zod.string()},
+ blockedByDialog: false,
+ concurrency: 'page',
+ verifyFilesSchema: {file: true},
+ handler: run,
+ }))(config.resolved);
+ const page = createMockMcpPage();
+ const context = createMockMcpContext({selectedPage: page});
+ const browser = getMockBrowser();
+ context.ensureBrowser.resolves(browser);
+ context.validatePath.resolves('/tmp/file');
+ const waitForInitialization = async () => {
+ started.resolve();
+ await initialization.promise;
+ };
+ const getContext = async () => {
+ if (stage === 'context') {
+ await waitForInitialization();
+ }
+ return context;
+ };
+ if (stage === 'browser') {
+ context.ensureBrowser.callsFake(async () => {
+ await waitForInitialization();
+ return browser;
+ });
+ } else if (stage === 'page') {
+ page.init.callsFake(waitForInitialization);
+ } else if (stage === 'files') {
+ context.validatePath.callsFake(async () => {
+ await waitForInitialization();
+ return '/tmp/file';
+ });
+ } else if (stage === 'telemetry') {
+ context.getDevToolsData.callsFake(async () => {
+ await waitForInitialization();
+ return {};
+ });
+ }
+ const responseHandle = sinon.stub(McpResponse.prototype, 'handle');
+ const setPage = sinon.spy(McpResponse.prototype, 'setPage');
+ const telemetry = sinon.createStubInstance(ClearcutLogger);
+ sinon.stub(ClearcutLogger, 'get').returns(telemetry);
+ sinon.stub(Date, 'now').returns(1_000);
+ const controller = new AbortController();
+ const abandonBrowser = sinon.spy();
+ const handler = new ToolHandler(
+ tool,
+ config,
+ getContext,
+ abandonBrowser,
+ );
+ const pending = handler.handle(
+ {file: '/tmp/file'},
+ {signal: controller.signal},
+ );
+ await started.promise;
+ controller.abort();
+ await assert.rejects(pending, {name: 'AbortError'});
+ const invocation = {
+ toolName: tool.name,
+ params: {file: '/tmp/file'},
+ schema: tool.schema,
+ success: false,
+ latencyMs: 0,
+ devToolsData: undefined,
+ pageUrl: undefined,
+ };
+ if (stage === 'context') {
+ sinon.assert.notCalled(telemetry.logToolInvocation);
+ } else {
+ sinon.assert.calledOnceWithExactly(
+ telemetry.logToolInvocation,
+ invocation,
+ );
+ }
+ const acquired = sinon.spy();
+ const probe = context.taskQueue.scheduleTask().then(guard => {
+ acquired();
+ return guard;
+ });
+ await settle();
+ if (stage === 'context' || stage === 'browser') {
+ sinon.assert.calledOnceWithExactly(acquired);
+ } else {
+ sinon.assert.notCalled(acquired);
+ }
+ initialization.resolve();
+ (await probe)[Symbol.dispose]();
+ await settle();
+ if (stage === 'context') {
+ sinon.assert.notCalled(context.ensureBrowser);
+ } else if (stage === 'browser') {
+ sinon.assert.notCalled(context.consumeReconnectNotice);
+ } else if (stage === 'files') {
+ sinon.assert.notCalled(context.getSelectedMcpPage);
+ } else if (stage === 'page') {
+ sinon.assert.notCalled(setPage);
+ } else {
+ sinon.assert.notCalled(context.getSelectedMcpPageUrl);
+ }
+ sinon.assert.notCalled(responseHandle);
+ if (stage === 'context') {
+ sinon.assert.notCalled(telemetry.logToolInvocation);
+ } else {
+ sinon.assert.calledOnceWithExactly(
+ telemetry.logToolInvocation,
+ invocation,
+ );
+ }
+ sinon.assert.notCalled(abandonBrowser);
+ assert.deepStrictEqual(
+ getEventListeners(controller.signal, 'abort'),
+ [],
+ );
+ });
+ }
+
+ it('serializes select_page after a cancelled selection finishes', async () => {
+ const config = parseConfig();
+ const context = createMockMcpContext();
+ context.ensureBrowser.resolves(getMockBrowser());
+ const oldPage = createMockMcpPage();
+ const nextPage = createMockMcpPage();
+ context.getPageById.withArgs(1).returns(oldPage);
+ context.getPageById.withArgs(2).returns(nextPage);
+ const initialization = Promise.withResolvers<void>();
+ oldPage.init.returns(initialization.promise);
+ sinon
+ .stub(McpResponse.prototype, 'handle')
+ .resolves({content: [], structuredContent: {}});
+ const handler = new ToolHandler(
+ selectPage(config.resolved),
+ config,
+ async () => context,
+ sinon.spy(),
+ );
+ const controller = new AbortController();
+ const pending = handler.handle({pageId: 1}, {signal: controller.signal});
+ await settle();
+ sinon.assert.calledOnceWithExactly(oldPage.init, {emulateFocus: true});
+ controller.abort();
+ await assert.rejects(pending, {name: 'AbortError'});
+ const next = handler.handle({pageId: 2});
+ await settle();
+ sinon.assert.notCalled(nextPage.init);
+ sinon.assert.notCalled(context.selectPage);
+ initialization.resolve();
+ assert.strictEqual((await next).isError, undefined);
+ sinon.assert.calledTwice(context.selectPage);
+ sinon.assert.calledWithExactly(context.selectPage.firstCall, oldPage);
+ sinon.assert.calledWithExactly(context.selectPage.secondCall, nextPage);
+ });
+
+ it('retains the queue while cancelled response processing settles', async () => {
+ const config = parseConfig();
+ const runner = new TaskRunner();
+ const context = createMockMcpContext({taskRunner: runner});
+ context.ensureBrowser.resolves(getMockBrowser());
+ const page = createMockMcpPage();
+ context.getPageById.returns(page);
+ const processing =
+ Promise.withResolvers<Awaited<ReturnType<McpResponse['handle']>>>();
+ const responseHandle = sinon
+ .stub(McpResponse.prototype, 'handle')
+ .returns(processing.promise);
+ const handler = new ToolHandler(
+ selectPage(config.resolved),
+ config,
+ async () => context,
+ sinon.spy(),
+ );
+ const controller = new AbortController();
+ const pending = handler.handle({pageId: 1}, {signal: controller.signal});
+ await settle();
+ sinon.assert.calledOnceWithExactly(responseHandle, context, 'default');
+ controller.abort();
+ await assert.rejects(pending, {name: 'AbortError'});
+ const paused = sinon.spy();
+ const pause = runner.pause().then(guard => {
+ paused();
+ return guard;
+ });
+ await settle();
+ sinon.assert.notCalled(paused);
+ processing.resolve({content: [], structuredContent: {}});
+ (await pause)[Symbol.dispose]();
+ sinon.assert.calledOnceWithExactly(paused);
+ });
+
+ it('skips context for an already cancelled request', async () => {
+ const getContext = sinon.stub().resolves(createMockMcpContext());
+ const config = parseConfig();
+ const handler = new ToolHandler(
+ evaluateScript(config.resolved),
+ config,
+ getContext,
+ sinon.spy(),
+ );
+ const controller = new AbortController();
+ controller.abort();
+ await assert.rejects(handler.handle({}, {signal: controller.signal}), {
+ name: 'AbortError',
+ });
+ sinon.assert.notCalled(getContext);
+ });
+ });
+
it('calls getSelectedMcpPage for page scoped tools when pageIdRouting is disabled', async () => {
let handlerCalled = false;
const config = parseConfig(['--no-page-id-routing']);
@@ -257,9 +692,9 @@ describe('ToolHandler', () => {
const otherHandler = createHandler(otherTool, mockContext);
const blockingResult = blockingHandler.handle({});
- await new Promise(resolve => setImmediate(resolve));
+ await settle();
const otherResult = otherHandler.handle({});
- await new Promise(resolve => setImmediate(resolve));
+ await settle();
finishWait();
await Promise.all([blockingResult, otherResult]);
@@ -306,7 +741,7 @@ describe('ToolHandler', () => {
const blockingResult = createHandler(blockingTool, mockContext).handle(
{},
);
- await new Promise(resolve => setImmediate(resolve));
+ await settle();
const waitingResult = await createHandler(
waitingTool,
mockContext,
@@ -390,10 +825,6 @@ describe('ToolHandler', () => {
);
}
- async function settle() {
- await new Promise(resolve => setImmediate(resolve));
- }
-
it('runs page tools on different pages at the same time', async () => {
sinon
.stub(McpResponse.prototype, 'handle')
diff --git a/tests/utils.ts b/tests/utils.ts
index ca52a165..822417e0 100644
--- a/tests/utils.ts
+++ b/tests/utils.ts
@@ -85,6 +85,10 @@ export function extractExtensionId(response: McpResponse): string {
return extensionId;
}
+export async function settle(): Promise<void> {
+ await new Promise(resolve => setImmediate(resolve));
+}
+
const browsers = new Map<string, Browser>();
let context: McpContext | undefined;
diff --git a/tests/utils/TaskRunner.test.ts b/tests/utils/TaskRunner.test.ts
index b804399e..3a3bc4da 100644
--- a/tests/utils/TaskRunner.test.ts
+++ b/tests/utils/TaskRunner.test.ts
@@ -5,15 +5,14 @@
*/
import assert from 'node:assert';
+import {getEventListeners} from 'node:events';
import {describe, it} from 'node:test';
import sinon from 'sinon';
import {TaskRunner, type TaskQueue} from '../../src/utils/TaskRunner.js';
-async function settle(): Promise<void> {
- await new Promise(resolve => setImmediate(resolve));
-}
+import {settle} from '../utils.js';
interface ControlledTask {
/** True once the queue is held. */
@@ -49,6 +48,124 @@ function createTree() {
}
describe('TaskRunner', () => {
+ describe('cancellation', () => {
+ it('preserves the reason for an already aborted signal', async () => {
+ const queue = new TaskRunner().createQueue();
+ const controller = new AbortController();
+ controller.abort('request cancelled');
+ await assert.rejects(queue.scheduleTask(controller.signal), reason => {
+ assert.strictEqual(reason, controller.signal.reason);
+ return true;
+ });
+ using guard = await queue.scheduleTask();
+ assert.deepStrictEqual(getEventListeners(controller.signal, 'abort'), []);
+ });
+
+ it('unblocks another child after cancelling a waiting parent', async () => {
+ const {parent, childA, childB} = createTree();
+ using running = await childA.scheduleTask();
+ const controller = new AbortController();
+ const waiting = parent.scheduleTask(controller.signal);
+ const b = start(childB);
+ await settle();
+ assert.strictEqual(b.started, false);
+ controller.abort();
+ await assert.rejects(waiting, {name: 'AbortError'});
+ await settle();
+ assert.strictEqual(b.started, true);
+ assert.deepStrictEqual(getEventListeners(controller.signal, 'abort'), []);
+ b.finish();
+ await b.done;
+ });
+
+ it('cancels acquisition while waiting', async () => {
+ const queue = new TaskRunner().createQueue();
+ const holder = await queue.scheduleTask();
+ const controller = new AbortController();
+ const pending = queue.scheduleTask(controller.signal);
+ controller.abort();
+ await assert.rejects(pending, {name: 'AbortError'});
+ holder[Symbol.dispose]();
+ using probe = await queue.scheduleTask();
+ assert.deepStrictEqual(getEventListeners(controller.signal, 'abort'), []);
+ });
+
+ it('keeps guard ownership with its caller after cancellation', async () => {
+ const queue = new TaskRunner().createQueue();
+ const controller = new AbortController();
+ const guard = await queue.scheduleTask(controller.signal);
+ assert.deepStrictEqual(getEventListeners(controller.signal, 'abort'), []);
+ controller.abort();
+ const next = start(queue);
+ await settle();
+ assert.strictEqual(next.started, false);
+ guard[Symbol.dispose]();
+ await settle();
+ assert.strictEqual(next.started, true);
+ next.finish();
+ await next.done;
+ assert.throws(() => guard[Symbol.dispose](), /already disposed/);
+ });
+
+ it('preserves the reason when cancelling a waiting task', async () => {
+ const queue = new TaskRunner().createQueue();
+ using holder = await queue.scheduleTask();
+ const controller = new AbortController();
+ const pending = queue.scheduleTask(controller.signal);
+ controller.abort('request cancelled');
+ await assert.rejects(pending, reason => {
+ assert.strictEqual(reason, controller.signal.reason);
+ return true;
+ });
+ assert.deepStrictEqual(getEventListeners(controller.signal, 'abort'), []);
+ });
+
+ it('keeps an acquired guard when aborted before promise delivery', async () => {
+ const queue = new TaskRunner().createQueue();
+ const controller = new AbortController();
+ const reason = new Error('request cancelled');
+ const pending = queue.scheduleTask(controller.signal);
+ controller.abort(reason);
+ const guard = await pending;
+ const next = start(queue);
+ await settle();
+ assert.strictEqual(next.started, false);
+ guard[Symbol.dispose]();
+ await settle();
+ assert.strictEqual(next.started, true);
+ next.finish();
+ await next.done;
+ });
+
+ for (const cancelFirst of [false, true]) {
+ it(`races disposal with abort (cancelFirst=${cancelFirst})`, async () => {
+ const queue = new TaskRunner().createQueue();
+ using running = await queue.scheduleTask();
+ const controller = new AbortController();
+ const pending = queue.scheduleTask(controller.signal);
+ const closed = new Error('Page closed');
+ if (cancelFirst) {
+ controller.abort();
+ queue.dispose(closed);
+ } else {
+ queue.dispose(closed);
+ controller.abort();
+ }
+ await assert.rejects(pending, reason => {
+ assert.strictEqual(
+ reason,
+ cancelFirst ? controller.signal.reason : closed,
+ );
+ return true;
+ });
+ assert.deepStrictEqual(
+ getEventListeners(controller.signal, 'abort'),
+ [],
+ );
+ });
+ }
+ });
+
it('runs tasks on unrelated queues at the same time', async () => {
const {childA, childB} = createTree();
const a = start(childA);
diff --git a/tests/utils/raceWithSignal.test.ts b/tests/utils/raceWithSignal.test.ts
new file mode 100644
index 00000000..bd8ec373
--- /dev/null
+++ b/tests/utils/raceWithSignal.test.ts
@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert/strict';
+import {getEventListeners} from 'node:events';
+import {describe, it} from 'node:test';
+
+import {raceWithSignal} from '../../src/utils/raceWithSignal.js';
+
+describe('raceWithSignal', () => {
+ it('returns the result and removes the abort listener', async () => {
+ const controller = new AbortController();
+ assert.strictEqual(
+ await raceWithSignal(Promise.resolve(42), controller.signal),
+ 42,
+ );
+ assert.deepStrictEqual(getEventListeners(controller.signal, 'abort'), []);
+ });
+
+ it('propagates rejection and removes the abort listener', async () => {
+ const controller = new AbortController();
+ const error = new Error('operation failed');
+ await assert.rejects(
+ raceWithSignal(Promise.reject(error), controller.signal),
+ reason => reason === error,
+ );
+ assert.deepStrictEqual(getEventListeners(controller.signal, 'abort'), []);
+ });
+
+ for (const alreadyAborted of [false, true]) {
+ it(`preserves cancellation and observes late rejection (alreadyAborted=${alreadyAborted})`, async () => {
+ const controller = new AbortController();
+ const operation = Promise.withResolvers<void>();
+ if (alreadyAborted) {
+ controller.abort('request cancelled');
+ }
+ const result = raceWithSignal(operation.promise, controller.signal);
+ controller.abort('request cancelled');
+ await assert.rejects(result, reason => reason === 'request cancelled');
+ assert.deepStrictEqual(getEventListeners(controller.signal, 'abort'), []);
+ operation.reject(new Error('late failure'));
+ });
+ }
+});