Chrome DevTools for coding agents
fix: preserve task serialization on request cancellation (#3079)
lisa031403fd4e840c6a
diff --git a/src/BUILD.gn b/src/BUILD.gnindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.gnindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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'));+ });+ }+});