@vscode/component-explorer-cli 0.1.1-9 → 0.2.1-0

package/dist/mcp/McpServer.js

@@ -9,10 +9,40 @@ import '../external/vscode-observables/observables/dist/observableInternal/obser
 import '../external/vscode-observables/observables/dist/observableInternal/utils/utils.js';
 import '../external/vscode-observables/observables/dist/observableInternal/observables/observableFromEvent.js';
 import { buildExplorerUrl } from '../utils.js';
+import { TaskManager } from './TaskManager.js';
 
 // ---------------------------------------------------------------------------
 // Client-local state
 // ---------------------------------------------------------------------------
+class ImageLruCache {
+    _maxSize;
+    _entries = [];
+    constructor(_maxSize = 10) {
+        this._maxSize = _maxSize;
+    }
+    put(hash, image) {
+        const idx = this._entries.findIndex(e => e.hash === hash);
+        if (idx !== -1) {
+            this._entries.splice(idx, 1);
+        }
+        this._entries.unshift({ hash, image });
+        if (this._entries.length > this._maxSize) {
+            this._entries.length = this._maxSize;
+        }
+    }
+    get(hash) {
+        const idx = this._entries.findIndex(e => e.hash === hash);
+        if (idx === -1) {
+            return undefined;
+        }
+        const [entry] = this._entries.splice(idx, 1);
+        this._entries.unshift(entry);
+        return entry.image;
+    }
+    keys() {
+        return this._entries.map(e => e.hash);
+    }
+}
 class WatchList {
     _fixtureIds = new Set();
     _hashes = new Map();
@@ -100,6 +130,9 @@ class ComponentExplorerMcpServer extends Disposable {
     }
     _mcp;
     _watchList = new WatchList();
+    _imageLru = new ImageLruCache(10);
+    _taskManager = new TaskManager();
+    _taskLastReportedIndex = new Map();
     _pollFn;
     _noAutostartHint;
     _multiSessionTools = [];
@@ -110,6 +143,7 @@ class ComponentExplorerMcpServer extends Disposable {
         this._daemonConnection = _daemonConnection;
         this._pollFn = options.pollFn;
         this._noAutostartHint = options.noAutostartHint;
+        this._callTimeoutMs = options.callTimeoutMs ?? ComponentExplorerMcpServer._DEFAULT_CALL_TIMEOUT_MS;
         this._mcp = new McpServer({
             name: 'component-explorer',
             version: '0.1.0',
@@ -178,15 +212,27 @@ class ComponentExplorerMcpServer extends Disposable {
     _noDaemonError() {
         return noDaemonError(this._noAutostartHint);
     }
-    async _withDaemon(fn) {
+    static _DEFAULT_CALL_TIMEOUT_MS = 15_000;
+    _callTimeoutMs;
+    async _withDaemon(fn, options) {
         const daemon = await this._waitForDaemon();
         if (!daemon) {
             return this._noDaemonError();
         }
         try {
-            return await fn(daemon);
+            if (options?.noTimeout) {
+                return await fn(daemon);
+            }
+            const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error('__mcp_timeout__')), this._callTimeoutMs));
+            return await Promise.race([fn(daemon), timeout]);
         }
         catch (e) {
+            if (e instanceof Error && e.message === '__mcp_timeout__') {
+                return {
+                    content: [{ type: 'text', text: `Error: Operation timed out after ${this._callTimeoutMs / 1000}s. Retry, if the error persists, restart the involved session using the restart_session tool and retry.` }],
+                    isError: true,
+                };
+            }
             if (isPipeConnectionError(e)) {
                 this._log('debug', { type: 'daemon-call-failed', error: String(e) });
                 this._handleDisconnect();
@@ -212,7 +258,7 @@ class ComponentExplorerMcpServer extends Disposable {
                     if (event.type === 'source-change' && event.sessionName && event.sourceTreeId) {
                         this._updateSessionSourceTreeId(event.sessionName, event.sourceTreeId);
                     }
-                    if (event.type === 'ref-change') {
+                    if (event.type === 'ref-change' || event.type === 'session-change') {
                         await this._refreshSessions();
                     }
                     this._log(event.type === 'log' && event.level === 'debug' ? 'debug' : 'info', event);
@@ -292,11 +338,37 @@ class ComponentExplorerMcpServer extends Disposable {
         }
     }
     // -- Tool registration ---------------------------------------------------
+    _filterFixtures(allFixtures, fixtureIdPattern, labelPattern) {
+        let fixtureIdRegex;
+        if (fixtureIdPattern) {
+            try {
+                fixtureIdRegex = new RegExp(fixtureIdPattern);
+            }
+            catch {
+                return { error: `Error: Invalid fixtureIdPattern: ${fixtureIdPattern}` };
+            }
+        }
+        let labelRegex;
+        if (labelPattern) {
+            try {
+                labelRegex = new RegExp(labelPattern);
+            }
+            catch {
+                return { error: `Error: Invalid labelPattern: ${labelPattern}` };
+            }
+        }
+        return {
+            fixtures: allFixtures.filter(f => (!fixtureIdRegex || fixtureIdRegex.test(f.fixtureId)) &&
+                (!labelRegex || f.labels.some(l => labelRegex.test(l)))),
+        };
+    }
     _registerTools() {
         this._registerListFixtures();
         this._registerScreenshot();
         this._registerCompareScreenshot();
         this._registerApproveDiff();
+        this._registerReviewVisual();
+        this._registerCheckVisuals();
         this._registerEvaluateJs();
         this._registerDebugReloadPage();
         this._registerWatchAdd();
@@ -305,12 +377,23 @@ class ComponentExplorerMcpServer extends Disposable {
         this._registerWatchCompare();
         this._registerWaitForUpdate();
         this._registerSessions();
+        this._registerRestartSession();
+        this._registerOpenSession();
+        this._registerCloseSession();
+        this._registerUpdateSessionRef();
         this._registerGetUrl();
+        this._registerCheckStability();
+        this._registerCheckTask();
+        this._registerCancelTask();
+        this._registerDebugGetImageByHash();
+        this._registerDebugSetBrowserVisibility();
     }
     _registerListFixtures() {
         this._mcp.registerTool('list_fixtures', {
             description: 'List all fixtures from a session',
             inputSchema: {
+                fixtureIdPattern: z.string().optional().describe('RegExp to filter fixtures by fixture ID'),
+                labelPattern: z.string().optional().describe('RegExp to filter fixtures by label (matched against inherited labels)'),
                 sessionName: z.string().optional().describe('Session name (defaults to first session)'),
                 sourceTreeId: z.string().optional().describe('Source tree ID (defaults to latest known)'),
             },
@@ -320,9 +403,13 @@ class ComponentExplorerMcpServer extends Disposable {
             this._log('debug', { type: 'tool-call', tool: 'list_fixtures', sessionName });
             return this._withSourceTreeRetry(async () => {
                 const sourceTreeId = args.sourceTreeId ?? this._sourceTreeId(sessionName);
-                const fixtures = await daemon.methods.fixtures.list({ sessionName, sourceTreeId });
+                const allFixtures = await daemon.methods.fixtures.list({ sessionName, sourceTreeId });
+                const filtered = this._filterFixtures(allFixtures, args.fixtureIdPattern, args.labelPattern);
+                if ('error' in filtered) {
+                    return { content: [{ type: 'text', text: filtered.error }], isError: true };
+                }
                 return {
-                    content: [{ type: 'text', text: JSON.stringify(fixtures, null, 2) }],
+                    content: [{ type: 'text', text: JSON.stringify(filtered.fixtures, null, 2) }],
                 };
             });
         }));
@@ -353,16 +440,46 @@ class ComponentExplorerMcpServer extends Disposable {
                 });
                 const r = result;
                 this._updateSessionSourceTreeId(sessionName, r.sourceTreeId);
+                // Cache image for debug_get_image_by_hash
+                if (r.hash && r.image) {
+                    this._imageLru.put(r.hash, r.image);
+                }
                 const info = {
                     hash: r.hash,
                     sourceTreeId: r.sourceTreeId,
                 };
-                if (r.errors && r.errors.length > 0) {
-                    info.errors = r.errors;
+                if (r.hasError) {
+                    info.hasError = true;
+                }
+                if (r.error) {
+                    info.error = r.error;
+                }
+                if (r.events && r.events.length > 0) {
+                    info.events = r.events;
+                }
+                if (r.resultData !== undefined) {
+                    info.resultData = r.resultData;
                 }
                 if (r.isStable !== undefined) {
                     info.isStable = r.isStable;
                 }
+                // Visual review status
+                if (r.hash) {
+                    try {
+                        const allFixtures = await daemon.methods.fixtures.list({ sessionName, sourceTreeId });
+                        const fixture = allFixtures.find(f => f.fixtureId === args.fixtureId);
+                        const descriptions = fixture?.expectedVisualDescriptions ?? [];
+                        const review = await daemon.methods.visualReview.getStatus({
+                            fixtureId: args.fixtureId,
+                            expectedVisualDescriptions: [...descriptions],
+                            screenshotHash: r.hash,
+                        });
+                        info.review = review;
+                    }
+                    catch {
+                        // Visual review not available — ignore
+                    }
+                }
                 const content = [];
                 if (r.isStable === false && r.stabilityScreenshots) {
                     // Not stable: return all distinct screenshots
@@ -417,12 +534,32 @@ class ComponentExplorerMcpServer extends Disposable {
                     match: r.match,
                     baselineHash: r.baselineHash,
                     currentHash: r.currentHash,
+                    baselineSourceTreeId,
+                    currentSourceTreeId,
                 };
-                if (r.baselineErrors && r.baselineErrors.length > 0) {
-                    info.baselineErrors = r.baselineErrors;
+                if (r.baselineHasError) {
+                    info.baselineHasError = true;
+                }
+                if (r.baselineError) {
+                    info.baselineError = r.baselineError;
+                }
+                if (r.baselineEvents && r.baselineEvents.length > 0) {
+                    info.baselineEvents = r.baselineEvents;
+                }
+                if (r.baselineResultData !== undefined) {
+                    info.baselineResultData = r.baselineResultData;
+                }
+                if (r.currentHasError) {
+                    info.currentHasError = true;
                 }
-                if (r.currentErrors && r.currentErrors.length > 0) {
-                    info.currentErrors = r.currentErrors;
+                if (r.currentError) {
+                    info.currentError = r.currentError;
+                }
+                if (r.currentEvents && r.currentEvents.length > 0) {
+                    info.currentEvents = r.currentEvents;
+                }
+                if (r.currentResultData !== undefined) {
+                    info.currentResultData = r.currentResultData;
                 }
                 if (r.approval) {
                     info.approval = r.approval;
@@ -463,6 +600,127 @@ class ComponentExplorerMcpServer extends Disposable {
         tool.disable();
         this._multiSessionTools.push(tool);
     }
+    _registerReviewVisual() {
+        this._mcp.registerTool('review_visual', {
+            description: 'Approve or reject a fixture\'s screenshot based on its expectedVisualDescriptions. ' +
+                'You must take a screenshot first and pass the resulting hash. ' +
+                'On approve, caches (expectedVisualDescriptions, screenshotHash) so future runs auto-approve.',
+            inputSchema: {
+                fixtureId: z.string().describe('The fixture ID'),
+                screenshotHash: z.string().describe('The screenshot hash (from a prior screenshot tool call)'),
+                verdict: z.enum(['approve', 'reject']).describe('Whether the visual matches expectations'),
+                comment: z.string().describe('Reason for the verdict'),
+                sessionName: z.string().optional().describe('Session name (defaults to first session)'),
+                sourceTreeId: z.string().optional().describe('Source tree ID (defaults to latest known)'),
+            },
+        }, async (args) => this._withDaemon(async (daemon) => {
+            const sessionName = args.sessionName ?? this._defaultSessionName();
+            this._log('debug', { type: 'tool-call', tool: 'review_visual', fixtureId: args.fixtureId, verdict: args.verdict });
+            return this._withSourceTreeRetry(async () => {
+                const sourceTreeId = args.sourceTreeId ?? this._sourceTreeId(sessionName);
+                // Get fixture descriptions
+                const allFixtures = await daemon.methods.fixtures.list({ sessionName, sourceTreeId });
+                const fixture = allFixtures.find(f => f.fixtureId === args.fixtureId);
+                if (!fixture) {
+                    return { content: [{ type: 'text', text: `Fixture not found: ${args.fixtureId}` }], isError: true };
+                }
+                if (fixture.expectedVisualDescriptions.length === 0) {
+                    return { content: [{ type: 'text', text: `Fixture ${args.fixtureId} has no expectedVisualDescriptions — nothing to review.` }], isError: true };
+                }
+                if (args.verdict === 'approve') {
+                    await daemon.methods.visualReview.approve({
+                        fixtureId: args.fixtureId,
+                        expectedVisualDescriptions: [...fixture.expectedVisualDescriptions],
+                        screenshotHash: args.screenshotHash,
+                        comment: args.comment,
+                    });
+                    return {
+                        content: [{ type: 'text', text: `Approved: ${args.fixtureId} (hash: ${args.screenshotHash})` }],
+                    };
+                }
+                else {
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({
+                                    fixtureId: args.fixtureId,
+                                    verdict: 'rejected',
+                                    comment: args.comment,
+                                    screenshotHash: args.screenshotHash,
+                                    expectedVisualDescriptions: fixture.expectedVisualDescriptions,
+                                }, null, 2) }],
+                    };
+                }
+            });
+        }));
+    }
+    _registerCheckVisuals() {
+        this._mcp.registerTool('check_visuals', {
+            description: 'Batch check visual review status for fixtures that have expectedVisualDescription. ' +
+                'Returns lists of approved, needs-review, and no-expectation fixtures.',
+            inputSchema: {
+                fixtureIdPattern: z.string().optional().describe('RegExp to filter fixtures by fixture ID'),
+                labelPattern: z.string().optional().describe('RegExp to filter fixtures by label'),
+                sessionName: z.string().optional().describe('Session name (defaults to first session)'),
+                sourceTreeId: z.string().optional().describe('Source tree ID (defaults to latest known)'),
+            },
+            annotations: { readOnlyHint: true },
+        }, async (args) => this._withDaemon(async (daemon) => {
+            const sessionName = args.sessionName ?? this._defaultSessionName();
+            this._log('debug', { type: 'tool-call', tool: 'check_visuals', sessionName });
+            return this._withSourceTreeRetry(async () => {
+                const sourceTreeId = args.sourceTreeId ?? this._sourceTreeId(sessionName);
+                const allFixtures = await daemon.methods.fixtures.list({ sessionName, sourceTreeId });
+                const filtered = this._filterFixtures(allFixtures, args.fixtureIdPattern, args.labelPattern);
+                if ('error' in filtered) {
+                    return { content: [{ type: 'text', text: filtered.error }], isError: true };
+                }
+                const approved = [];
+                const needsReview = [];
+                const noExpectation = [];
+                // Take screenshots for all fixtures with expectations
+                const withExpectations = filtered.fixtures.filter(f => f.expectedVisualDescriptions.length > 0);
+                const withoutExpectations = filtered.fixtures.filter(f => f.expectedVisualDescriptions.length === 0);
+                for (const f of withoutExpectations) {
+                    noExpectation.push(f.fixtureId);
+                }
+                for (const f of withExpectations) {
+                    try {
+                        const screenshotResult = await daemon.methods.screenshots.take({
+                            fixtureId: f.fixtureId, sessionName, sourceTreeId, includeImage: true,
+                        });
+                        const hash = screenshotResult.hash;
+                        const image = screenshotResult.image;
+                        if (hash && image) {
+                            this._imageLru.put(hash, image);
+                        }
+                        if (!hash) {
+                            needsReview.push({ fixtureId: f.fixtureId, reason: 'screenshot-failed' });
+                            continue;
+                        }
+                        const review = await daemon.methods.visualReview.getStatus({
+                            fixtureId: f.fixtureId,
+                            expectedVisualDescriptions: [...f.expectedVisualDescriptions],
+                            screenshotHash: hash,
+                        });
+                        if (review === 'no-expectations') {
+                            noExpectation.push(f.fixtureId);
+                        }
+                        else if (typeof review === 'object' && review.status === 'approved') {
+                            approved.push({ fixtureId: f.fixtureId, screenshotHash: hash });
+                        }
+                        else {
+                            needsReview.push({ fixtureId: f.fixtureId, screenshotHash: hash, reason: 'needs-review' });
+                        }
+                    }
+                    catch {
+                        needsReview.push({ fixtureId: f.fixtureId, reason: 'error' });
+                    }
+                }
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ approved, needsReview, noExpectation }, null, 2) }],
+                };
+            });
+        }));
+    }
     _registerEvaluateJs() {
         this._mcp.registerTool('evaluate_js', {
             description: 'Evaluate a JavaScript expression in the browser page where fixtures are rendered, for debugging purposes. ' +
@@ -660,8 +918,13 @@ class ComponentExplorerMcpServer extends Disposable {
             const events = await daemon.methods.events();
             const iterator = events[Symbol.asyncIterator]();
             try {
-                const timeout = new Promise(resolve => setTimeout(() => resolve('timeout'), 5000));
+                const deadline = Date.now() + 5000;
                 while (true) {
+                    const remaining = deadline - Date.now();
+                    if (remaining <= 0) {
+                        return { content: [{ type: 'text', text: JSON.stringify({ timeout: true, sessionName, sourceTreeId: knownSourceTreeId }, null, 2) }] };
+                    }
+                    const timeout = new Promise(resolve => setTimeout(() => resolve('timeout'), remaining));
                     const next = iterator.next();
                     const result = await Promise.race([next, timeout]);
                     if (result === 'timeout') {
@@ -676,7 +939,10 @@ class ComponentExplorerMcpServer extends Disposable {
                         this._updateSessionSourceTreeId(ev.sessionName, ev.sourceTreeId);
                     }
                     if (ev.type === 'ref-change') {
-                        await this._refreshSessions();
+                        const refreshResult = await Promise.race([this._refreshSessions(), timeout]);
+                        if (refreshResult === 'timeout') {
+                            return { content: [{ type: 'text', text: JSON.stringify({ timeout: true, sessionName, sourceTreeId: knownSourceTreeId }, null, 2) }] };
+                        }
                     }
                     const newSourceTreeId = this._sourceTreeId(sessionName);
                     if (newSourceTreeId && newSourceTreeId !== knownSourceTreeId) {
@@ -737,6 +1003,90 @@ class ComponentExplorerMcpServer extends Disposable {
             };
         }));
     }
+    _registerRestartSession() {
+        this._mcp.registerTool('restart_session', {
+            description: 'Restart a session by disposing its browser page and dev server, then recreating them. ' +
+                'Use this when a session appears stuck (e.g. after a timeout).',
+            inputSchema: {
+                sessionName: z.string().optional().describe('Session name to restart (defaults to first session)'),
+            },
+            annotations: { destructiveHint: true },
+        }, async (args) => this._withDaemon(async (daemon) => {
+            const sessionName = args.sessionName ?? this._defaultSessionName();
+            this._log('info', { type: 'tool-call', tool: 'restart_session', sessionName });
+            const sessions = await daemon.methods.restartSession({ sessionName });
+            this._sessions = sessions;
+            return {
+                content: [{ type: 'text', text: `Session '${sessionName}' restarted.\n` + JSON.stringify(sessions, null, 2) }],
+            };
+        }));
+    }
+    _registerOpenSession() {
+        this._mcp.registerTool('open_session', {
+            description: 'Open a new worktree-backed session at a given git ref. ' +
+                'The ref can be a branch name, tag, commit SHA, or the special value "INDEX" to snapshot staged changes. ' +
+                'The daemon allocates a reusable worktree slot from a fixed pool (max configured in component-explorer.json). ' +
+                'Returns the updated session list on success.',
+            inputSchema: {
+                name: z.string().describe('Unique session name (e.g. "baseline", "bisect")'),
+                ref: z.string().describe('Git ref: branch, tag, commit SHA, or "INDEX" for staged changes'),
+            },
+        }, async (args) => this._withDaemon(async (daemon) => {
+            this._log('info', { type: 'tool-call', tool: 'open_session', name: args.name, ref: args.ref });
+            const result = await daemon.methods.openSession({ name: args.name, ref: args.ref });
+            if ('error' in result) {
+                return { content: [{ type: 'text', text: result.error }], isError: true };
+            }
+            this._sessions = result.sessions;
+            this._updateMultiSessionToolVisibility();
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result.sessions, null, 2) }],
+            };
+        }, { noTimeout: true }));
+    }
+    _registerCloseSession() {
+        this._mcp.registerTool('close_session', {
+            description: 'Close a dynamic worktree session and release its worktree slot back to the pool. ' +
+                'Cannot close static sessions configured in component-explorer.json.',
+            inputSchema: {
+                name: z.string().describe('Session name to close'),
+            },
+            annotations: { destructiveHint: true },
+        }, async (args) => this._withDaemon(async (daemon) => {
+            this._log('info', { type: 'tool-call', tool: 'close_session', name: args.name });
+            const result = await daemon.methods.closeSession({ name: args.name });
+            if ('error' in result) {
+                return { content: [{ type: 'text', text: result.error }], isError: true };
+            }
+            this._sessions = result.sessions;
+            this._updateMultiSessionToolVisibility();
+            return {
+                content: [{ type: 'text', text: `Session '${args.name}' closed.\n` + JSON.stringify(result.sessions, null, 2) }],
+            };
+        }));
+    }
+    _registerUpdateSessionRef() {
+        this._mcp.registerTool('update_session_ref', {
+            description: 'Change the git ref of an existing dynamic session. ' +
+                'The worktree is checked out to the new ref and Vite\'s HMR handles the incremental update (no server restart). ' +
+                'Fails if the worktree has uncommitted changes — the error will list the dirty files. ' +
+                'The ref can be a branch, tag, commit SHA, or "INDEX" for staged changes.',
+            inputSchema: {
+                name: z.string().describe('Session name to update'),
+                ref: z.string().describe('New git ref: branch, tag, commit SHA, or "INDEX"'),
+            },
+        }, async (args) => this._withDaemon(async (daemon) => {
+            this._log('info', { type: 'tool-call', tool: 'update_session_ref', name: args.name, ref: args.ref });
+            const result = await daemon.methods.updateSessionRef({ name: args.name, ref: args.ref });
+            if ('error' in result) {
+                return { content: [{ type: 'text', text: result.error }], isError: true };
+            }
+            this._sessions = result.sessions;
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result.sessions, null, 2) }],
+            };
+        }, { noTimeout: true }));
+    }
     _registerGetUrl() {
         this._mcp.registerTool('get_url', {
             description: 'Get URL(s) for viewing fixtures. Returns the Component Explorer UI URL by default, ' +
@@ -814,6 +1164,198 @@ class ComponentExplorerMcpServer extends Disposable {
             };
         });
     }
+    _registerCheckStability() {
+        this._mcp.registerTool('check_stability', {
+            description: 'Check rendering stability of fixtures. Each fixture is unmounted, re-mounted, and screenshotted 3 times (~3s per fixture). ' +
+                'Returns results directly if finished within ~10s, otherwise returns a taskId for polling via check_task. ' +
+                'When returning a taskId, includes partial results collected so far.',
+            inputSchema: {
+                fixtureIdPattern: z.string().optional().describe('RegExp to filter fixtures by fixture ID'),
+                labelPattern: z.string().optional().describe('RegExp to filter fixtures by label (matched against inherited labels)'),
+                sessionName: z.string().optional().describe('Session name (defaults to first session)'),
+                sourceTreeId: z.string().optional().describe('Source tree ID (defaults to latest known)'),
+            },
+            annotations: { readOnlyHint: true },
+        }, async (args) => this._withDaemon(async (daemon) => {
+            const sessionName = args.sessionName ?? this._defaultSessionName();
+            this._log('debug', { type: 'tool-call', tool: 'check_stability', sessionName, fixtureIdPattern: args.fixtureIdPattern, labelPattern: args.labelPattern });
+            return this._withSourceTreeRetry(async () => {
+                const sourceTreeId = args.sourceTreeId ?? this._sourceTreeId(sessionName);
+                const allFixtures = await daemon.methods.fixtures.list({ sessionName, sourceTreeId });
+                const filtered = this._filterFixtures(allFixtures, args.fixtureIdPattern, args.labelPattern);
+                if ('error' in filtered) {
+                    return { content: [{ type: 'text', text: filtered.error }], isError: true };
+                }
+                const fixtures = filtered.fixtures;
+                this._log('info', { type: 'check-stability-start', total: fixtures.length, filtered: allFixtures.length - fixtures.length });
+                const task = this._taskManager.startTask(async (report, signal) => {
+                    const results = [];
+                    report({ completed: 0, total: fixtures.length, partialResult: results });
+                    for (let i = 0; i < fixtures.length; i++) {
+                        if (signal.aborted) {
+                            break;
+                        }
+                        const fixture = fixtures[i];
+                        this._log('info', { type: 'check-stability-progress', fixtureId: fixture.fixtureId, index: i + 1, total: fixtures.length });
+                        const result = await daemon.methods.screenshots.take({
+                            fixtureId: fixture.fixtureId,
+                            sessionName,
+                            sourceTreeId,
+                            includeImage: false,
+                            stabilityCheck: true,
+                        });
+                        const r = result;
+                        results.push({
+                            fixtureId: fixture.fixtureId,
+                            isStable: r.isStable ?? true,
+                            screenshots: r.stabilityScreenshots?.map(s => ({ hash: s.hash, delayMs: s.delayMs })) ?? [],
+                        });
+                        report({ completed: i + 1, total: fixtures.length, partialResult: results });
+                    }
+                    const stable = results.filter(r => r.isStable).length;
+                    return {
+                        fixtures: results,
+                        summary: { total: results.length, stable, unstable: results.length - stable },
+                    };
+                });
+                const waited = await this._taskManager.waitForTask(task.id, 10_000);
+                if (!waited) {
+                    return { content: [{ type: 'text', text: 'Error: task disappeared' }], isError: true };
+                }
+                if (waited.done) {
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(waited.result, null, 2) }],
+                    };
+                }
+                const partial = waited.progress.partialResult;
+                this._taskLastReportedIndex.set(task.id, partial.length);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                taskId: task.id,
+                                status: 'running',
+                                progress: { completed: waited.progress.completed, total: waited.progress.total },
+                                elapsedMs: waited.elapsedMs,
+                                results: partial,
+                            }, null, 2),
+                        }],
+                };
+            });
+        }));
+    }
+    _registerCheckTask() {
+        this._mcp.registerTool('check_task', {
+            description: 'Check on a running task. Waits up to ~2s for completion; if still running, returns progress and new results since last check.',
+            inputSchema: {
+                taskId: z.string().describe('The task ID returned by a previous tool call'),
+            },
+            annotations: { readOnlyHint: true },
+        }, async (args) => {
+            const waited = await this._taskManager.waitForTask(args.taskId, 2_000);
+            if (!waited) {
+                this._taskLastReportedIndex.delete(args.taskId);
+                return {
+                    content: [{ type: 'text', text: `Error: No task found with id '${args.taskId}'` }],
+                    isError: true,
+                };
+            }
+            if (waited.done) {
+                const lastIndex = this._taskLastReportedIndex.get(args.taskId) ?? 0;
+                this._taskLastReportedIndex.delete(args.taskId);
+                const fullResult = waited.result;
+                const newResults = fullResult.fixtures.slice(lastIndex);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                status: 'done',
+                                newResults,
+                                summary: fullResult.summary,
+                            }, null, 2),
+                        }],
+                };
+            }
+            const partial = waited.progress.partialResult;
+            const lastIndex = this._taskLastReportedIndex.get(args.taskId) ?? 0;
+            const newResults = partial.slice(lastIndex);
+            this._taskLastReportedIndex.set(args.taskId, partial.length);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            taskId: args.taskId,
+                            status: 'running',
+                            progress: { completed: waited.progress.completed, total: waited.progress.total },
+                            elapsedMs: waited.elapsedMs,
+                            newResults,
+                        }, null, 2),
+                    }],
+            };
+        });
+    }
+    _registerCancelTask() {
+        this._mcp.registerTool('cancel_task', {
+            description: 'Cancel a running task',
+            inputSchema: {
+                taskId: z.string().describe('The task ID to cancel'),
+            },
+        }, async (args) => {
+            const task = this._taskManager.getTask(args.taskId);
+            if (!task) {
+                return {
+                    content: [{ type: 'text', text: `Error: No task found with id '${args.taskId}'` }],
+                    isError: true,
+                };
+            }
+            this._taskManager.removeTask(args.taskId);
+            return {
+                content: [{ type: 'text', text: `Task '${args.taskId}' cancelled.` }],
+            };
+        });
+    }
+    _registerDebugGetImageByHash() {
+        this._mcp.registerTool('debug_get_image_by_hash', {
+            description: 'Retrieve a recently-taken screenshot image by its hash. ' +
+                'Keeps the last ~10 images in an LRU cache. ' +
+                'Useful for debugging when screenshot hashes behave unexpectedly.',
+            inputSchema: {
+                hash: z.string().describe('The screenshot hash to look up'),
+            },
+            annotations: { readOnlyHint: true },
+        }, async (args) => {
+            const image = this._imageLru.get(args.hash);
+            if (!image) {
+                return {
+                    content: [{ type: 'text', text: `No cached image for hash '${args.hash}'. Available hashes: ${this._imageLru.keys().join(', ') || '(none)'}` }],
+                    isError: true,
+                };
+            }
+            return {
+                content: [
+                    { type: 'text', text: `Image for hash: ${args.hash}` },
+                    { type: 'image', data: image, mimeType: 'image/png' },
+                ],
+            };
+        });
+    }
+    _registerDebugSetBrowserVisibility() {
+        this._mcp.registerTool('debug_set_browser_visibility', {
+            description: 'Show or hide the browser window used for rendering fixtures. ' +
+                'Only use this tool when the user explicitly asks to show or hide the browser. ' +
+                'Do not call this tool automatically or as part of other workflows. ' +
+                'Note: changing visibility closes the current browser instance, so the next screenshot or evaluate_js call will relaunch it.',
+            inputSchema: {
+                visible: z.boolean().describe('true to show the browser window (headed mode), false to hide it (headless mode)'),
+            },
+            annotations: { destructiveHint: true },
+        }, async (args) => this._withDaemon(async (daemon) => {
+            await daemon.methods.setBrowserVisibility({ visible: args.visible });
+            return {
+                content: [{ type: 'text', text: `Browser is now ${args.visible ? 'visible (headed)' : 'hidden (headless)'}.` }],
+            };
+        }));
+    }
 }
 
 export { ComponentExplorerMcpServer, DaemonConnection };