auto-feedback 0.1.0

package/build/tools/launch-web-server.d.ts

@@ -0,0 +1,13 @@
+/**
+ * launch_web_server MCP tool (PROC-01)
+ * Spawns a dev server process and waits for it to become ready
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SessionManager } from "../session-manager.js";
+/**
+ * Register the launch_web_server tool with the MCP server
+ *
+ * @param server - MCP server instance
+ * @param sessionManager - Session manager for resource tracking
+ */
+export declare function registerLaunchWebServerTool(server: McpServer, sessionManager: SessionManager): void;

package/build/tools/launch-web-server.js

@@ -0,0 +1,88 @@
+/**
+ * launch_web_server MCP tool (PROC-01)
+ * Spawns a dev server process and waits for it to become ready
+ */
+import path from "path";
+import { z } from "zod";
+import { createToolError, createToolResult } from "../utils/errors.js";
+import { spawnCrossPlatform, attachProcessListeners, } from "../process/launcher.js";
+import { detectServerReady } from "../process/monitor.js";
+import { createProcessResource } from "../process/cleanup.js";
+import { attachProcessCollector } from "../capture/process-collector.js";
+/**
+ * Register the launch_web_server tool with the MCP server
+ *
+ * @param server - MCP server instance
+ * @param sessionManager - Session manager for resource tracking
+ */
+export function registerLaunchWebServerTool(server, sessionManager) {
+    server.tool("launch_web_server", "Launch a web dev server and wait for it to be ready. Use to start npm/vite/webpack dev servers for testing.", {
+        sessionId: z.string().describe("Session ID to track this process"),
+        command: z
+            .string()
+            .describe("Command to run (e.g., 'npm', 'npx', 'node')"),
+        args: z
+            .array(z.string())
+            .describe("Command arguments (e.g., ['run', 'dev'])"),
+        cwd: z.string().describe("Working directory for the project"),
+        port: z
+            .number()
+            .int()
+            .min(1)
+            .max(65535)
+            .describe("Expected port the server will listen on"),
+        timeoutMs: z
+            .number()
+            .int()
+            .min(1000)
+            .max(300000)
+            .optional()
+            .describe("Readiness timeout in ms (default: 60000)"),
+    }, async ({ sessionId, command, args, cwd, port, timeoutMs }) => {
+        try {
+            // Validate session exists
+            const session = sessionManager.get(sessionId);
+            if (!session) {
+                return createToolError(`Session not found: ${sessionId}`, "The session may have already been ended or never existed", "Create a session first with create_session.");
+            }
+            console.error(`[launch_web_server] Launching: ${command} ${args.join(" ")} in ${cwd} on port ${port}`);
+            // Resolve cwd to absolute path
+            const resolvedCwd = path.resolve(cwd);
+            // Spawn the process
+            const child = spawnCrossPlatform(command, args, { cwd: resolvedCwd });
+            // Attach logging listeners
+            attachProcessListeners(child, `WebServer:${port}`);
+            // Attach process output collector for retrieval
+            const processCollector = attachProcessCollector(child);
+            sessionManager.setProcessCollector(sessionId, `WebServer:${port}`, processCollector);
+            // Register process as a session resource for automatic cleanup
+            const resource = createProcessResource(child, "web-server");
+            sessionManager.addResource(sessionId, resource);
+            // Wait for server readiness
+            try {
+                await detectServerReady(child, port, timeoutMs ?? 60000);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const processExited = child.exitCode !== null;
+                return createToolError("Web server failed to become ready", processExited
+                    ? `Process exited with code ${child.exitCode}. ${message}`
+                    : message, "Check the command and port. The process may have crashed -- check server logs.");
+            }
+            return createToolResult({
+                sessionId,
+                type: "web-server",
+                pid: child.pid,
+                port,
+                status: "ready",
+                command,
+                args,
+                cwd: resolvedCwd,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return createToolError("Unexpected error launching web server", message, "Check command, arguments, and working directory are correct.");
+        }
+    });
+}

package/build/tools/launch-windows-exe.d.ts

@@ -0,0 +1,13 @@
+/**
+ * launch_windows_exe MCP tool (PROC-03)
+ * Spawns a Windows executable and tracks its process as a session resource
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SessionManager } from "../session-manager.js";
+/**
+ * Register the launch_windows_exe tool with the MCP server
+ *
+ * Spawns a Windows .exe, waits briefly for immediate spawn errors,
+ * and registers the process as a session resource for cleanup.
+ */
+export declare function registerLaunchWindowsExeTool(server: McpServer, sessionManager: SessionManager): void;

package/build/tools/launch-windows-exe.js

@@ -0,0 +1,81 @@
+/**
+ * launch_windows_exe MCP tool (PROC-03)
+ * Spawns a Windows executable and tracks its process as a session resource
+ */
+import path from "path";
+import { z } from "zod";
+import { createToolError, createToolResult } from "../utils/errors.js";
+import { spawnCrossPlatform, attachProcessListeners, } from "../process/launcher.js";
+import { createProcessResource } from "../process/cleanup.js";
+import { attachProcessCollector } from "../capture/process-collector.js";
+/**
+ * Register the launch_windows_exe tool with the MCP server
+ *
+ * Spawns a Windows .exe, waits briefly for immediate spawn errors,
+ * and registers the process as a session resource for cleanup.
+ */
+export function registerLaunchWindowsExeTool(server, sessionManager) {
+    server.tool("launch_windows_exe", "Launch a Windows executable and track its process. Use to start .exe applications for GUI testing.", {
+        sessionId: z.string().describe("Session ID to track this process"),
+        exePath: z.string().describe("Absolute path to the .exe file"),
+        args: z
+            .array(z.string())
+            .optional()
+            .describe("Command line arguments for the executable"),
+        cwd: z
+            .string()
+            .optional()
+            .describe("Working directory (defaults to exe's directory)"),
+    }, async ({ sessionId, exePath, args, cwd }) => {
+        try {
+            // Validate session exists
+            const session = sessionManager.get(sessionId);
+            if (!session) {
+                return createToolError(`Session not found: ${sessionId}`, "The session may have already been ended or never existed", "Create a session first with create_session.");
+            }
+            // Resolve paths
+            const resolvedExePath = path.resolve(exePath);
+            const resolvedCwd = cwd
+                ? path.resolve(cwd)
+                : path.dirname(resolvedExePath);
+            console.error(`[launch_windows_exe] Launching: ${resolvedExePath}`);
+            // Spawn the process
+            const child = spawnCrossPlatform(resolvedExePath, args ?? [], {
+                cwd: resolvedCwd,
+            });
+            attachProcessListeners(child, `WinExe:${path.basename(resolvedExePath)}`);
+            // Attach process output collector for retrieval
+            const processCollector = attachProcessCollector(child);
+            sessionManager.setProcessCollector(sessionId, `WinExe:${path.basename(resolvedExePath)}`, processCollector);
+            // Wait briefly for immediate spawn errors
+            await new Promise((resolve, reject) => {
+                const errorHandler = (err) => reject(err);
+                child.on("error", errorHandler);
+                setTimeout(() => {
+                    child.removeListener("error", errorHandler);
+                    resolve();
+                }, 1000);
+            });
+            // Check if process exited immediately (bad path, missing deps, etc.)
+            if (child.exitCode !== null) {
+                return createToolError(`Process exited immediately with code ${child.exitCode}`, `Attempted to launch: ${resolvedExePath}`, "Check that the .exe path is correct and the application can run from the command line");
+            }
+            // Register as session resource for cleanup
+            const resource = createProcessResource(child, "windows-exe");
+            sessionManager.addResource(sessionId, resource);
+            return createToolResult({
+                sessionId,
+                type: "windows-exe",
+                pid: child.pid,
+                status: "running",
+                exePath: resolvedExePath,
+                args: args ?? [],
+                cwd: resolvedCwd,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return createToolError("Failed to launch Windows executable", message, "Check the .exe path is correct and the file exists.");
+        }
+    });
+}

package/build/tools/navigate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * navigate MCP tool
+ * Navigates to URLs and uses browser back/forward on web or Electron pages
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SessionManager } from "../session-manager.js";
+/**
+ * Register the navigate tool with the MCP server
+ *
+ * @param server - MCP server instance
+ * @param sessionManager - Session manager for resource tracking
+ */
+export declare function registerNavigateTool(server: McpServer, sessionManager: SessionManager): void;

package/build/tools/navigate.js

@@ -0,0 +1,137 @@
+/**
+ * navigate MCP tool
+ * Navigates to URLs and uses browser back/forward on web or Electron pages
+ */
+import { z } from "zod";
+import { createToolError, createScreenshotResult } from "../utils/errors.js";
+import { capturePlaywrightPage } from "../screenshot/capture.js";
+import { optimizeScreenshot } from "../screenshot/optimize.js";
+import { getActivePage } from "../interaction/selectors.js";
+/**
+ * Register the navigate tool with the MCP server
+ *
+ * @param server - MCP server instance
+ * @param sessionManager - Session manager for resource tracking
+ */
+export function registerNavigateTool(server, sessionManager) {
+    server.tool("navigate", "Navigate to a URL or use browser back/forward on a web or Electron page. Returns a screenshot of the resulting page. Use to load pages, follow links, or retrace steps.", {
+        sessionId: z
+            .string()
+            .describe("Session ID from create_session"),
+        action: z
+            .enum(["goto", "back", "forward"])
+            .default("goto")
+            .describe("Navigation action: goto (load URL), back (browser back), forward (browser forward)"),
+        url: z
+            .string()
+            .optional()
+            .describe("URL to navigate to (required when action is 'goto')"),
+        pageIdentifier: z
+            .string()
+            .optional()
+            .describe("URL or 'electron' to target a specific page. Omit if session has only one page."),
+        waitUntil: z
+            .enum(["load", "domcontentloaded", "commit"])
+            .optional()
+            .describe("When to consider navigation complete (default: 'load'). Do NOT use 'networkidle' — it is unreliable."),
+        timeout: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe("Max wait time in ms (default: 30000)"),
+    }, async ({ sessionId, action, url, pageIdentifier, waitUntil, timeout, }) => {
+        try {
+            // Validate session exists
+            const session = sessionManager.get(sessionId);
+            if (!session) {
+                const availableSessions = sessionManager.list();
+                return createToolError(`Session not found: ${sessionId}`, "The session may have already been ended", availableSessions.length > 0
+                    ? `Available sessions: ${availableSessions.join(", ")}`
+                    : "Create a session first with create_session.");
+            }
+            // Validate URL is provided for goto action
+            if (action === "goto" && !url) {
+                return createToolError("URL is required when action is 'goto'", "The 'goto' action navigates to a specific URL", "Provide a url parameter, e.g. url: 'https://example.com'");
+            }
+            // Find the active page
+            const pageResult = getActivePage(sessionManager, sessionId, pageIdentifier);
+            if (!pageResult.success) {
+                return createToolError(pageResult.error, `Session: ${sessionId}`, pageResult.availablePages
+                    ? `Available pages: ${pageResult.availablePages.join(", ")}`
+                    : undefined);
+            }
+            const { page, identifier: currentIdentifier, type: pageType } = pageResult;
+            const effectiveTimeout = timeout ?? 30000;
+            const effectiveWaitUntil = waitUntil ?? "load";
+            // Perform the navigation action
+            if (action === "goto") {
+                await page.goto(url, {
+                    waitUntil: effectiveWaitUntil,
+                    timeout: effectiveTimeout,
+                });
+                // Update PageReference URL in SessionManager for web pages
+                // so page discovery continues to work with the new URL
+                if (pageType === "web" && currentIdentifier !== "electron") {
+                    const oldRef = sessionManager.getPageRef(sessionId, currentIdentifier);
+                    if (oldRef) {
+                        sessionManager.removePageRef(sessionId, currentIdentifier);
+                        sessionManager.setPageRef(sessionId, url, {
+                            ...oldRef,
+                            url: url,
+                        });
+                    }
+                }
+            }
+            else if (action === "back") {
+                const response = await page.goBack({
+                    waitUntil: effectiveWaitUntil,
+                    timeout: effectiveTimeout,
+                });
+                if (response === null) {
+                    return createToolError("Cannot go back", "No previous page in browser history", "Navigate to a URL first before using back.");
+                }
+            }
+            else {
+                // action === "forward"
+                const response = await page.goForward({
+                    waitUntil: effectiveWaitUntil,
+                    timeout: effectiveTimeout,
+                });
+                if (response === null) {
+                    return createToolError("Cannot go forward", "No forward page in browser history", "Use back first before using forward.");
+                }
+            }
+            // Capture post-navigation screenshot
+            const rawBuffer = await capturePlaywrightPage(page, {
+                fullPage: false,
+            });
+            const optimized = await optimizeScreenshot(rawBuffer, {
+                maxWidth: 1280,
+                quality: 80,
+            });
+            const imageBase64 = optimized.data.toString("base64");
+            return createScreenshotResult({
+                sessionId,
+                action,
+                url: page.url(),
+                success: true,
+            }, imageBase64, optimized.mimeType);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // Timeout: page took too long to load
+            if (message.includes("Timeout") ||
+                message.includes("timeout")) {
+                return createToolError("Navigation timed out", `Page did not finish loading within ${timeout ?? 30000}ms`, "Increase the timeout, use waitUntil: 'domcontentloaded' for faster resolution, or check if the URL is correct.");
+            }
+            // Network errors (Chrome: net::ERR_, Firefox: NS_ERROR_)
+            if (message.includes("net::ERR_") ||
+                message.includes("NS_ERROR_")) {
+                return createToolError("Network error during navigation", message, "Check if the URL is correct and the server is running. For local servers, ensure the dev server is started.");
+            }
+            // Default error
+            return createToolError("Navigation failed", `Action: ${action}, URL: ${url ?? "N/A"} — ${message}`, "Take a screenshot to check the current page state.");
+        }
+    });
+}

package/build/tools/run-workflow.d.ts

@@ -0,0 +1,14 @@
+/**
+ * run_workflow MCP tool
+ * Executes multi-step workflows on web or Electron pages with per-step
+ * screenshot capture and diagnostic log tracking.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SessionManager } from "../session-manager.js";
+/**
+ * Register the run_workflow tool with the MCP server
+ *
+ * @param server - MCP server instance
+ * @param sessionManager - Session manager for resource tracking
+ */
+export declare function registerRunWorkflowTool(server: McpServer, sessionManager: SessionManager): void;

package/build/tools/run-workflow.js

@@ -0,0 +1,207 @@
+/**
+ * run_workflow MCP tool
+ * Executes multi-step workflows on web or Electron pages with per-step
+ * screenshot capture and diagnostic log tracking.
+ */
+import { z } from "zod";
+import { createToolError } from "../utils/errors.js";
+import { getActivePage } from "../interaction/selectors.js";
+import { executeWorkflow, validateStep } from "../workflow/executor.js";
+/**
+ * Register the run_workflow tool with the MCP server
+ *
+ * @param server - MCP server instance
+ * @param sessionManager - Session manager for resource tracking
+ */
+export function registerRunWorkflowTool(server, sessionManager) {
+    server.tool("run_workflow", "Execute a multi-step workflow on a web or Electron page. Runs actions in sequence, captures screenshot and logs at each step, stops on first error. Use for form filling, navigation flows, or multi-step UI verification with pass/fail assertions.", {
+        sessionId: z
+            .string()
+            .describe("Session ID from create_session"),
+        steps: z
+            .array(z.object({
+            action: z
+                .enum(["click", "type", "navigate", "screenshot", "wait", "assert"])
+                .describe("Action to perform"),
+            selector: z
+                .string()
+                .optional()
+                .describe("Element selector — CSS, text=, role=, testid=, xpath= (required for click, type, wait)"),
+            text: z
+                .string()
+                .optional()
+                .describe("Text to type (required for type action)"),
+            url: z
+                .string()
+                .optional()
+                .describe("URL to navigate to (required for navigate action)"),
+            button: z
+                .enum(["left", "right", "middle"])
+                .optional()
+                .describe("Mouse button for click (default: left)"),
+            clickCount: z
+                .number()
+                .int()
+                .min(1)
+                .max(3)
+                .optional()
+                .describe("Click count: 1=single, 2=double, 3=triple"),
+            pressSequentially: z
+                .boolean()
+                .optional()
+                .describe("Type one key at a time instead of fill (default: false)"),
+            clear: z
+                .boolean()
+                .optional()
+                .describe("Clear field before typing (default: true)"),
+            fullPage: z
+                .boolean()
+                .optional()
+                .describe("Capture full scrollable page in screenshot (default: false)"),
+            state: z
+                .enum(["visible", "hidden", "attached", "detached"])
+                .optional()
+                .describe("State to wait for (default: visible)"),
+            timeout: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Step timeout in ms (default: 30000)"),
+            assertType: z
+                .enum([
+                "exists",
+                "not-exists",
+                "visible",
+                "hidden",
+                "text-equals",
+                "text-contains",
+                "has-attribute",
+                "attribute-equals",
+                "enabled",
+                "disabled",
+                "checked",
+                "not-checked",
+                "value-equals",
+            ])
+                .optional()
+                .describe("Assertion type (required for assert action). Checks element state and reports pass/fail."),
+            expected: z
+                .string()
+                .optional()
+                .describe("Expected value for text-equals, text-contains, value-equals, attribute-equals assertions"),
+            attribute: z
+                .string()
+                .optional()
+                .describe("Attribute name for has-attribute, attribute-equals assertions"),
+        }))
+            .min(1)
+            .max(20)
+            .describe("Action steps to execute in order (max 20)"),
+        pageIdentifier: z
+            .string()
+            .optional()
+            .describe("URL or 'electron' to target a specific page. Omit if session has only one page."),
+    }, async ({ sessionId, steps, pageIdentifier }) => {
+        try {
+            // 1. Validate session exists
+            const session = sessionManager.get(sessionId);
+            if (!session) {
+                const availableSessions = sessionManager.list();
+                return createToolError(`Session not found: ${sessionId}`, "The session may have already been ended", availableSessions.length > 0
+                    ? `Available sessions: ${availableSessions.join(", ")}`
+                    : "Create a session first with create_session.");
+            }
+            // 2. Discover page
+            const pageResult = getActivePage(sessionManager, sessionId, pageIdentifier);
+            if (!pageResult.success) {
+                return createToolError(pageResult.error, `Session: ${sessionId}`, pageResult.availablePages
+                    ? `Available pages: ${pageResult.availablePages.join(", ")}`
+                    : undefined);
+            }
+            const { page, identifier } = pageResult;
+            // 3. Validate all steps up front before executing any
+            const validationErrors = [];
+            for (let i = 0; i < steps.length; i++) {
+                const error = validateStep(steps[i], i);
+                if (error) {
+                    validationErrors.push(error);
+                }
+            }
+            if (validationErrors.length > 0) {
+                return createToolError("Workflow validation failed", validationErrors.join("; "), "Fix the step parameters and retry.");
+            }
+            // 4. Execute workflow
+            const result = await executeWorkflow({
+                page,
+                steps,
+                sessionManager,
+                sessionId,
+                pageIdentifier: identifier,
+            });
+            // 5. Build multi-content response
+            const content = [];
+            // Summary header
+            const summary = {
+                workflow: result.failedStep !== undefined ? "stopped" : "complete",
+                totalSteps: result.totalSteps,
+                completedSteps: result.completedSteps,
+                failedAtStep: result.failedStep,
+            };
+            // Include assertion counts when assert steps are present
+            const assertSteps = result.steps.filter((r) => r.assertion);
+            if (assertSteps.length > 0) {
+                summary.assertionsPassed = result.steps.filter((r) => r.assertion?.passed === true).length;
+                summary.assertionsFailed = result.steps.filter((r) => r.assertion?.passed === false).length;
+            }
+            content.push({
+                type: "text",
+                text: JSON.stringify(summary, null, 2),
+            });
+            // Per-step text metadata and screenshot images
+            for (const r of result.steps) {
+                const stepMeta = {
+                    step: r.stepIndex,
+                    action: r.action,
+                    success: r.success,
+                    error: r.error,
+                    consoleLogs: r.consoleDelta.length,
+                    errors: r.errorDelta.length,
+                };
+                // Include assertion result when present
+                if (r.assertion) {
+                    stepMeta.assertion = r.assertion;
+                }
+                // Include error details inline when present
+                if (r.errorDelta.length > 0) {
+                    stepMeta.errorDetails = r.errorDelta;
+                }
+                // Include console errors inline when present
+                const consoleErrors = r.consoleDelta.filter((e) => e.level === "error");
+                if (consoleErrors.length > 0) {
+                    stepMeta.consoleErrors = consoleErrors;
+                }
+                content.push({
+                    type: "text",
+                    text: JSON.stringify(stepMeta, null, 2),
+                });
+                // Add screenshot image if captured
+                if (r.screenshotBase64 && r.screenshotMimeType) {
+                    content.push({
+                        type: "image",
+                        data: r.screenshotBase64,
+                        mimeType: r.screenshotMimeType,
+                    });
+                }
+            }
+            return {
+                content,
+                isError: result.failedStep !== undefined,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return createToolError("Workflow execution failed", message, "Take a screenshot to check current page state.");
+        }
+    });
+}

package/build/tools/screenshot-desktop.d.ts

@@ -0,0 +1,13 @@
+/**
+ * screenshot_desktop MCP tool
+ * Captures a screenshot of a Windows desktop application window by PID
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SessionManager } from "../session-manager.js";
+/**
+ * Register the screenshot_desktop tool with the MCP server
+ *
+ * @param server - MCP server instance
+ * @param sessionManager - Session manager for resource tracking
+ */
+export declare function registerScreenshotDesktopTool(server: McpServer, sessionManager: SessionManager): void;

package/build/tools/screenshot-desktop.js

@@ -0,0 +1,80 @@
+/**
+ * screenshot_desktop MCP tool
+ * Captures a screenshot of a Windows desktop application window by PID
+ */
+import { z } from "zod";
+import { createToolError, createScreenshotResult } from "../utils/errors.js";
+import { captureDesktopWindow } from "../screenshot/capture.js";
+import { optimizeScreenshot } from "../screenshot/optimize.js";
+/**
+ * Register the screenshot_desktop tool with the MCP server
+ *
+ * @param server - MCP server instance
+ * @param sessionManager - Session manager for resource tracking
+ */
+export function registerScreenshotDesktopTool(server, sessionManager) {
+    server.tool("screenshot_desktop", "Capture a screenshot of a Windows desktop application window by PID. Use after launch_windows_exe to see the app.", {
+        sessionId: z
+            .string()
+            .describe("Session ID (for resource tracking)"),
+        pid: z
+            .number()
+            .int()
+            .positive()
+            .describe("Process ID of the target window (from launch_windows_exe result)"),
+        maxWidth: z
+            .number()
+            .int()
+            .min(100)
+            .max(3840)
+            .optional()
+            .describe("Max image width in pixels (default: 1280)"),
+        quality: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe("WebP quality 1-100 (default: 80)"),
+    }, async ({ sessionId, pid, maxWidth, quality }) => {
+        try {
+            const session = sessionManager.get(sessionId);
+            if (!session) {
+                return createToolError(`Session not found: ${sessionId}`, "The session may have already been ended", "Create a session first with create_session.");
+            }
+            console.error(`[screenshot_desktop] Capturing window PID ${pid} for session ${sessionId}`);
+            // Capture raw PNG via node-screenshots
+            const rawBuffer = await captureDesktopWindow(pid);
+            // Optimize: resize + WebP
+            const optimized = await optimizeScreenshot(rawBuffer, {
+                maxWidth: maxWidth ?? 1280,
+                quality: quality ?? 80,
+            });
+            const imageBase64 = optimized.data.toString("base64");
+            return createScreenshotResult({
+                sessionId,
+                type: "desktop",
+                pid,
+                mode: "viewport",
+                width: optimized.width,
+                height: optimized.height,
+                originalSize: rawBuffer.length,
+                optimizedSize: optimized.data.length,
+            }, imageBase64, optimized.mimeType);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // Provide specific guidance based on error type
+            let suggestedFix = "Check the PID is correct and the window is visible.";
+            if (message.includes("No window found")) {
+                suggestedFix =
+                    "The process may not have a visible window yet. Wait a moment and retry, or check the PID from launch_windows_exe output.";
+            }
+            else if (message.includes("minimized")) {
+                suggestedFix =
+                    "The window is minimized. The user needs to restore it before capturing.";
+            }
+            return createToolError("Failed to capture desktop screenshot", message, suggestedFix);
+        }
+    });
+}