@testdriverai/mcp 7.10.0-canary.0 → 7.10.1-test

package/mcp-server/dist/server.mjs

@@ -10,14 +10,19 @@ process.env.TD_DEBUG = "true";
 import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { randomUUID } from "crypto";
+import * as http from "http";
 import * as Sentry from "@sentry/node";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import { z } from "zod";
-import { generateActionCode } from "./codegen.js";
-import { getProvisionOptions, SessionStartInputSchema } from "./provision-types.js";
+import * as core from "./core/actions.js";
+import { NoActiveSessionError } from "./core/actions.js";
+import { resolveE2bTemplateId, resolveOs } from "./env-utils.js";
+import { SessionStartInputSchema } from "./provision-types.js";
 import { sessionManager } from "./session.js";
 // =============================================================================
 // Sentry
@@ -47,9 +52,7 @@ function resolveChannel(ver) {
     return "stable";
 }
 function resolveSentryEnvironment(ver) {
-    if (process.env.TD_ENV && VALID_ENVS.has(process.env.TD_ENV))
-        return process.env.TD_ENV;
-    return CHANNEL_TO_ENV[resolveChannel(ver)] || "production";
+    return resolveChannel(ver);
 }
 const activeChannel = resolveChannel(version);
 const sentryEnvironment = resolveSentryEnvironment(version);
@@ -66,8 +69,8 @@ if (isSentryEnabled()) {
             "https://452bd5a00dbd83a38ee8813e11c57694@o4510262629236736.ingest.us.sentry.io/4510480443637760",
         environment: sentryEnvironment,
         release: version,
-        sampleRate: 1.0,
-        tracesSampleRate: 1.0,
+        sampleRate: 0.01,
+        tracesSampleRate: 0.01,
         sendDefaultPii: true,
         integrations: [Sentry.httpIntegration(), Sentry.nodeContextIntegration()],
         initialScope: {
@@ -178,10 +181,6 @@ const RESOURCE_URI = "ui://testdriver/mcp-app.html";
 // Resource URI base for serving screenshot blobs (with dynamic IDs)
 const SCREENSHOT_RESOURCE_BASE = "screenshot://testdriver/screenshot";
 const CROPPED_IMAGE_RESOURCE_BASE = "screenshot://testdriver/cropped";
-// SDK instance (will be initialized on session start)
-let sdk = null;
-// Last screenshot base64 for check comparisons
-let lastScreenshotBase64 = null;
 // Map of image ID -> image data
 const imageStore = new Map();
 // Counter for generating unique image IDs
@@ -230,42 +229,135 @@ function getSessionData(session) {
     };
 }
 /**
- * Check if session is ready for use - returns error result if not
- * This helper provides clear, actionable error messages for the AI
- *
- * Auto-extends the session on each successful check to prevent expiry during active use
+ * Map a {@link NoActiveSessionError} thrown by the core into the exact same
+ * "no/expired session" tool result the server's old `requireActiveSession`
+ * produced. Kept byte-identical so external behavior is unchanged.
  */
-function requireActiveSession() {
-    const session = sessionManager.getCurrentSession();
-    // No session ever created
-    if (!sdk || !session) {
-        return {
-            valid: false,
-            error: createToolResult(false, "ERROR: No active session. You must call session_start first to create a sandbox before using any other tools.", {
-                error: "NO_SESSION",
-                action: "session_start",
-                message: "No sandbox session exists. Call session_start to create one."
-            })
-        };
+function noSessionResult(err) {
+    if (err.code === "SESSION_EXPIRED") {
+        return createToolResult(false, "ERROR: Session has expired or timed out. The sandbox is no longer available. You must call session_start again to create a new sandbox session before continuing.", {
+            error: "SESSION_EXPIRED",
+            action: "session_start",
+            message: "The previous sandbox session has expired. Call session_start to create a new one.",
+            expiredSessionId: err.expiredSessionId,
+        });
     }
-    // Session exists but has expired
-    if (!sessionManager.isSessionValid(session.sessionId)) {
-        // Clear the SDK reference since the sandbox is no longer available
-        sdk = null;
+    return createToolResult(false, "ERROR: No active session. You must call session_start first to create a sandbox before using any other tools.", {
+        error: "NO_SESSION",
+        action: "session_start",
+        message: "No sandbox session exists. Call session_start to create one.",
+    });
+}
+/**
+ * Map a core {@link ActionResult} into an MCP CallToolResult, storing images as
+ * resource URIs (the core returns BARE base64, which is what `storeImage` wants).
+ */
+function resultToMcp(r) {
+    const data = { ...r.data };
+    for (const img of r.images ?? []) {
+        const uri = storeImage(img.base64, img.kind);
+        if (img.kind === "cropped")
+            data.croppedImageResourceUri = uri;
+        else
+            data.screenshotResourceUri = uri;
+    }
+    return createToolResult(r.ok, r.text, data, r.code);
+}
+const DEFAULT_HEARTBEAT_MS = 3000;
+function makeProgressReporter(extra) {
+    const progressToken = extra?._meta?.progressToken;
+    // No token → client did not opt into progress. Return a no-op reporter.
+    if (progressToken === undefined || progressToken === null) {
         return {
-            valid: false,
-            error: createToolResult(false, "ERROR: Session has expired or timed out. The sandbox is no longer available. You must call session_start again to create a new sandbox session before continuing.", {
-                error: "SESSION_EXPIRED",
-                action: "session_start",
-                message: "The previous sandbox session has expired. Call session_start to create a new one.",
-                expiredSessionId: session.sessionId
-            })
+            report: () => { },
+            heartbeat: () => () => { },
         };
     }
-    // Auto-extend session on each command to prevent expiry during active use
-    // This resets the expiry timer back to the original keepAlive duration
-    sessionManager.refreshSession(session.sessionId);
-    return { valid: true };
+    let progress = 0;
+    const send = (message) => {
+        progress += 1;
+        // Fire-and-forget: a failed notification must never break the tool call.
+        void extra
+            .sendNotification({
+            method: "notifications/progress",
+            params: { progressToken, progress, message },
+        })
+            .catch((err) => {
+            logger.debug("progress: sendNotification failed", { error: String(err) });
+        });
+    };
+    return {
+        report: (message) => send(message),
+        heartbeat: (message, intervalMs = DEFAULT_HEARTBEAT_MS) => {
+            send(message);
+            const timer = setInterval(() => send(message), intervalMs);
+            // Don't let the heartbeat keep the event loop alive on its own.
+            timer.unref?.();
+            return () => clearInterval(timer);
+        },
+    };
+}
+// =============================================================================
+// Cancellation (MCP `notifications/cancelled` → `extra.signal`)
+// =============================================================================
+/** Thrown when a tool call is aborted by the client. */
+class ToolAbortError extends Error {
+    constructor(tool) {
+        super(`${tool} was cancelled by the client`);
+        this.name = "ToolAbortError";
+    }
+}
+/** Reject as soon as `signal` aborts. Used to race against long SDK calls. */
+function rejectOnAbort(signal, tool) {
+    if (!signal) {
+        // Never-resolving promise with a no-op cleanup — Promise.race ignores it.
+        return { promise: new Promise(() => { }), cleanup: () => { } };
+    }
+    let onAbort = () => { };
+    const promise = new Promise((_, reject) => {
+        onAbort = () => reject(new ToolAbortError(tool));
+        if (signal.aborted) {
+            onAbort();
+        }
+        else {
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+    });
+    return { promise, cleanup: () => signal.removeEventListener("abort", onAbort) };
+}
+/**
+ * Run a long-running SDK call, but settle as soon as the client aborts.
+ *
+ * The wrapped SDK methods are not themselves signal-aware, so on abort the
+ * underlying work keeps running to completion in the background — but the tool
+ * call returns promptly with a `ToolAbortError` instead of blocking the client.
+ * Callers that hold cleanable resources (e.g. `session_start`) should catch
+ * `ToolAbortError` and tear them down.
+ */
+async function raceAbort(signal, tool, work) {
+    if (signal?.aborted) {
+        throw new ToolAbortError(tool);
+    }
+    const { promise, cleanup } = rejectOnAbort(signal, tool);
+    try {
+        return await Promise.race([work, promise]);
+    }
+    finally {
+        cleanup();
+    }
+}
+/**
+ * If `error` is a client cancellation, return a "cancelled" tool result so the
+ * caller can `return` it; otherwise return null so normal error handling (log +
+ * Sentry + rethrow) proceeds. Keeps abort out of error reporting — a user
+ * cancelling is not a failure.
+ */
+function cancelledResultOrNull(error, tool) {
+    if (error instanceof ToolAbortError) {
+        logger.info(`${tool}: Cancelled by client`);
+        return createToolResult(false, `${tool} was cancelled.`, { action: tool, cancelled: true });
+    }
+    return null;
 }
 /**
  * Create tool result with structured content for MCP App
@@ -321,9 +413,6 @@ const server = isSentryEnabled()
         name: "testdriver",
         version: version,
     });
-// Element reference storage (for click/hover after find)
-// Stores actual Element instances - no raw coordinates as input
-const elementRefs = new Map();
 // =============================================================================
 // Register UI Resource
 // =============================================================================
@@ -412,188 +501,79 @@ Debug mode (connect to existing sandbox):
 - Use this to interactively debug failed tests without re-running from scratch`,
     inputSchema: SessionStartInputSchema,
     _meta: { ui: { resourceUri: RESOURCE_URI, expanded: true } },
-}, async (params) => {
+}, async (params, extra) => {
     const startTime = Date.now();
+    const progress = makeProgressReporter(extra);
+    // Resolve OS with priority: explicit param > TD_OS env var > "linux" default
+    // This mirrors the behavior of the Vitest hooks (hooks.mjs) which also reads TD_OS
+    const { os: resolvedOs, warning: osWarning } = resolveOs(params.os);
+    if (osWarning) {
+        logger.warn(`session_start: ${osWarning}`);
+    }
+    else if (!params.os && resolvedOs !== "linux") {
+        logger.info("session_start: Using TD_OS environment variable", { os: resolvedOs });
+    }
+    // Resolve E2B template ID with priority: explicit param > TD_E2B_TEMPLATE_ID env var
+    // This mirrors the behavior of the Vitest hooks (hooks.mjs) which also reads TD_E2B_TEMPLATE_ID
+    const resolvedE2bTemplateId = resolveE2bTemplateId(params.e2bTemplateId);
+    if (!params.e2bTemplateId && resolvedE2bTemplateId) {
+        logger.info("session_start: Using TD_E2B_TEMPLATE_ID environment variable", { e2bTemplateId: resolvedE2bTemplateId });
+    }
     logger.info("session_start: Starting", {
         type: params.type,
         url: params.url,
-        os: params.os,
+        os: resolvedOs,
         reconnect: params.reconnect,
         sandboxId: params.sandboxId,
     });
     try {
-        // Validate required fields for specific provision types (unless connecting to existing sandbox)
-        if (!params.sandboxId) {
-            if (params.type === "installer" && !params.installerUrl) {
-                return createToolResult(false, "installer type requires 'installerUrl' parameter", { error: "Missing required parameter: installerUrl" });
-            }
-            if (params.type === "electron" && !params.appPath) {
-                return createToolResult(false, "electron type requires 'appPath' parameter", { error: "Missing required parameter: appPath" });
-            }
+        // The core owns session creation, SDK init, connect, provisioning and the
+        // initial screenshot. We keep the abort race + heartbeat scaffolding here:
+        // a heartbeat ticks while the long provisioning await is in flight, and the
+        // whole core call is raced against the client's abort signal so cancellation
+        // still returns promptly. Progress messages from the core are forwarded.
+        const stopHeartbeat = progress.heartbeat(params.sandboxId
+            ? `Connecting to existing sandbox ${params.sandboxId}...`
+            : "Starting session...");
+        let result;
+        try {
+            result = await raceAbort(extra.signal, "session_start", core.sessionStart(params, { os: resolvedOs, e2bTemplateId: resolvedE2bTemplateId }, { onProgress: (m) => progress.report(m) }));
         }
-        // Create new session
-        const newSession = sessionManager.createSession({
-            os: params.os,
-            keepAlive: params.keepAlive,
-            testFile: params.testFile,
-        });
-        logger.debug("session_start: Session created", { sessionId: newSession.sessionId });
-        // Determine API root
-        const apiRoot = params.apiRoot || process.env.TD_API_ROOT || "https://api.testdriver.ai";
-        logger.debug("session_start: Using API root", { apiRoot });
-        // Initialize SDK
-        logger.debug("session_start: Initializing SDK");
-        const TestDriverSDK = (await import("../../sdk.js")).default;
-        // Determine preview mode from environment variable
-        // TD_PREVIEW can be "ide", "browser", or "none"
-        // Default to "ide" so the live preview shows within the IDE
-        const previewMode = process.env.TD_PREVIEW || "ide";
-        logger.debug("session_start: Preview mode", { preview: previewMode });
-        // Get IP from params or environment (for self-hosted instances)
-        const instanceIp = params.ip || process.env.TD_IP;
-        // Get API key - check multiple sources for GitHub Copilot coding agent compatibility
-        // 1. TD_API_KEY (standard environment variable)
-        // 2. COPILOT_MCP_TD_API_KEY (fallback for GitHub Copilot coding agent)
-        const apiKey = process.env.TD_API_KEY || process.env.COPILOT_MCP_TD_API_KEY || "";
-        if (!apiKey) {
-            logger.error("session_start: No API key found", {
-                hasTD_API_KEY: !!process.env.TD_API_KEY,
-                hasCOPILOT_MCP_TD_API_KEY: !!process.env.COPILOT_MCP_TD_API_KEY,
-                availableEnvVars: Object.keys(process.env).filter(k => k.includes('TD') || k.includes('COPILOT_MCP'))
-            });
-            return createToolResult(false, "No API key found. Please set TD_API_KEY or COPILOT_MCP_TD_API_KEY environment variable.", {
-                error: "Missing API key",
-                hint: "For GitHub Copilot coding agent, create a Copilot environment secret named COPILOT_MCP_TD_API_KEY"
-            });
+        finally {
+            stopHeartbeat();
         }
-        logger.debug("session_start: API key found", {
-            source: process.env.TD_API_KEY ? "TD_API_KEY" : "COPILOT_MCP_TD_API_KEY",
-            keyPrefix: apiKey.substring(0, 7) + "..."
-        });
-        sdk = new TestDriverSDK(apiKey, {
-            os: params.os,
-            logging: false,
-            apiRoot,
-            preview: previewMode,
-            ip: instanceIp,
-        });
-        // Handle sandboxId mode - connect to existing sandbox (debug-on-failure mode)
-        if (params.sandboxId) {
-            logger.info("session_start: Connecting to existing sandbox (debug mode)", { sandboxId: params.sandboxId });
-            await sdk.connect({
-                sandboxId: params.sandboxId,
-                keepAlive: params.keepAlive,
-            });
-            // Get sandbox ID
-            const instance = sdk.getInstance();
-            logger.info("session_start: Connected to existing sandbox", { instanceId: instance?.instanceId });
-            sessionManager.activateSession(newSession.sessionId, instance?.instanceId || params.sandboxId);
-            // Set Sentry context for error tracking
-            setSessionContext(newSession.sessionId, instance?.instanceId);
-            // Capture screenshot of current state
-            logger.debug("session_start: Capturing screenshot of existing sandbox");
-            const screenshotBase64 = await sdk.agent.system.captureScreenBase64(1, false, true);
-            let screenshotResourceUri;
-            if (screenshotBase64) {
-                screenshotResourceUri = storeImage(screenshotBase64, "screenshot");
-                lastScreenshotBase64 = screenshotBase64;
-            }
-            const duration = Date.now() - startTime;
-            logger.info("session_start: Connected to existing sandbox", { duration, sessionId: newSession.sessionId, sandboxId: params.sandboxId });
-            return createToolResult(true, `Connected to existing sandbox (debug mode)
-Session: ${newSession.sessionId}
-Sandbox: ${params.sandboxId}
-Expires in: ${Math.round(params.keepAlive / 1000)}s
-
-You are now connected to the sandbox in its current state. Use find, click, type, etc. to interact.`, {
-                action: "session_start",
-                sessionId: newSession.sessionId,
-                sandboxId: params.sandboxId,
-                debugMode: true,
-                screenshotResourceUri,
-                duration
-            }, "// Connected to existing sandbox - no provision code needed");
+        const duration = Date.now() - startTime;
+        // Set Sentry context once the session id is known.
+        if (result.ok && typeof result.data.sessionId === "string") {
+            setSessionContext(result.data.sessionId, result.data.sandboxId || undefined);
         }
-        // Connect to sandbox
-        if (instanceIp) {
-            logger.info("session_start: Connecting to self-hosted instance...", { ip: instanceIp });
+        logger.info("session_start: Completed", { duration, ok: result.ok });
+        if (!result.ok) {
+            // Validation / missing-key failures: pass through with duration added.
+            return resultToMcp({ ...result, data: { ...result.data, duration } });
         }
-        else {
-            logger.info("session_start: Connecting to cloud sandbox...");
+        // Reproduce the server's exact success output (text + data) which differs
+        // from the core's neutral text. Images are mapped to resource URIs.
+        const data = { ...result.data, duration };
+        for (const img of result.images ?? []) {
+            const uri = storeImage(img.base64, img.kind);
+            if (img.kind === "cropped")
+                data.croppedImageResourceUri = uri;
+            else
+                data.screenshotResourceUri = uri;
         }
-        await sdk.connect({
-            reconnect: params.reconnect,
-            keepAlive: params.keepAlive,
-            ip: instanceIp,
-        });
-        // Get sandbox ID
-        const instance = sdk.getInstance();
-        logger.info("session_start: Connected to sandbox", { instanceId: instance?.instanceId });
-        sessionManager.activateSession(newSession.sessionId, instance?.instanceId || "unknown");
-        // Set Sentry context for error tracking
-        setSessionContext(newSession.sessionId, instance?.instanceId);
-        // Get provision-specific options
-        const provisionOptions = getProvisionOptions(params);
-        let provisionCmd = "";
-        // Provision based on type
-        switch (params.type) {
-            case "chrome": {
-                const chromeOpts = provisionOptions;
-                logger.info("session_start: Provisioning Chrome", { url: chromeOpts.url });
-                await sdk.provision.chrome(chromeOpts);
-                provisionCmd = "provision.chrome";
-                logger.debug("session_start: Chrome provisioned");
-                break;
-            }
-            case "chromeExtension": {
-                const extOpts = provisionOptions;
-                logger.info("session_start: Provisioning Chrome Extension", { extensionPath: extOpts.extensionPath, extensionId: extOpts.extensionId });
-                await sdk.provision.chromeExtension(extOpts);
-                provisionCmd = "provision.chromeExtension";
-                logger.debug("session_start: Chrome Extension provisioned");
-                break;
-            }
-            case "vscode": {
-                const vscodeOpts = provisionOptions;
-                logger.info("session_start: Provisioning VS Code", { workspace: vscodeOpts.workspace });
-                await sdk.provision.vscode(vscodeOpts);
-                provisionCmd = "provision.vscode";
-                logger.debug("session_start: VS Code provisioned");
-                break;
-            }
-            case "installer": {
-                const installerOpts = provisionOptions;
-                logger.info("session_start: Provisioning installer", { url: installerOpts.url });
-                await sdk.provision.installer(installerOpts);
-                provisionCmd = "provision.installer";
-                logger.debug("session_start: Installer provisioned");
-                break;
-            }
-            case "electron": {
-                const electronOpts = provisionOptions;
-                logger.info("session_start: Provisioning Electron", { appPath: electronOpts.appPath });
-                await sdk.provision.electron(electronOpts);
-                provisionCmd = "provision.electron";
-                logger.debug("session_start: Electron app provisioned");
-                break;
-            }
-        }
-        // Capture initial screenshot after provisioning
-        logger.debug("session_start: Capturing initial screenshot");
-        const screenshotBase64 = await sdk.agent.system.captureScreenBase64(1, false, true);
-        let screenshotResourceUri;
-        if (screenshotBase64) {
-            screenshotResourceUri = storeImage(screenshotBase64, "screenshot");
-            lastScreenshotBase64 = screenshotBase64;
+        if (result.data.debugMode) {
+            // Debug (existing-sandbox) success text — preserve original wording.
+            const text = `Connected to existing sandbox (debug mode)
+Session: ${result.data.sessionId}
+Sandbox: ${result.data.sandboxId}
+Expires in: ${Math.round(params.keepAlive / 1000)}s
+
+You are now connected to the sandbox in its current state. Use find, click, type, etc. to interact.`;
+            return createToolResult(true, text, data, result.code);
         }
-        const duration = Date.now() - startTime;
-        logger.info("session_start: Completed", { duration, sessionId: newSession.sessionId, selfHosted: !!instanceIp });
-        // Generate the code for this provision action
-        const generatedCode = generateActionCode(provisionCmd, provisionOptions);
-        // Build debugger URL for the session
-        const debuggerUrl = instance?.debuggerUrl || (instanceIp ? `http://${instanceIp}:9222` : null);
-        const connectionType = instanceIp ? `Self-hosted (${instanceIp})` : "Cloud";
-        return createToolResult(true, `Session started: ${newSession.sessionId}\nConnection: ${connectionType}\nType: ${params.type}\nSandbox: ${instance?.instanceId}\nExpires in: ${Math.round(params.keepAlive / 1000)}s
+        // Normal provisioning success — append the EXACT dependency guidance block.
+        const text = `${result.text}
 
 IMPORTANT - If creating a new test project, use these EXACT dependencies in package.json:
 {
@@ -605,18 +585,23 @@ IMPORTANT - If creating a new test project, use these EXACT dependencies in pack
   "scripts": {
     "test": "vitest"
   }
-}`, {
-            action: "session_start",
-            sessionId: newSession.sessionId,
-            provisionType: params.type,
-            selfHosted: !!instanceIp,
-            instanceIp: instanceIp || undefined,
-            debuggerUrl,
-            screenshotResourceUri,
-            duration
-        }, generatedCode);
+}`;
+        return createToolResult(true, text, data, result.code);
     }
     catch (error) {
+        // On client cancellation, tear down the half-provisioned session so we
+        // don't leak a connected sandbox. The underlying SDK call may still be
+        // running in the background; best-effort cleanup is all we can do.
+        if (error instanceof ToolAbortError) {
+            logger.info("session_start: Cancelled by client, tearing down session");
+            try {
+                await core.disconnect();
+            }
+            catch (cleanupErr) {
+                logger.warn("session_start: Cleanup after cancel failed", { error: String(cleanupErr) });
+            }
+            return createToolResult(false, "Session start was cancelled.", { action: "session_start", cancelled: true });
+        }
         logger.error("session_start: Failed", { error: String(error) });
         captureException(error, { tags: { tool: "session_start" }, extra: { params } });
         throw error;
@@ -629,20 +614,15 @@ server.registerTool("session_status", {
 }, async () => {
     const startTime = Date.now();
     logger.info("session_status: Checking");
-    const session = sessionManager.getCurrentSession();
-    if (!session) {
-        logger.warn("session_status: No active session");
-        return createToolResult(false, "No active session", { error: "No active session. Call session_start first." });
-    }
-    const summary = sessionManager.getSessionSummary(session.sessionId);
+    const result = core.sessionStatus();
     const duration = Date.now() - startTime;
     logger.info("session_status: Completed", {
-        sessionId: session.sessionId,
-        status: session.status,
-        timeRemaining: summary?.timeRemaining,
-        duration
+        ok: result.ok,
+        sessionId: result.data.sessionId,
+        status: result.data.status,
+        duration,
     });
-    return createToolResult(true, `Session: ${session.sessionId}\nStatus: ${session.status}\nTime remaining: ${Math.round((summary?.timeRemaining || 0) / 1000)}s`, { action: "session_status", ...summary, sessionId: session.sessionId, status: session.status, duration });
+    return resultToMcp({ ...result, data: { ...result.data, duration } });
 });
 // Session Extend
 server.registerTool("session_extend", {
@@ -652,19 +632,18 @@ server.registerTool("session_extend", {
     }),
 }, async (params) => {
     logger.info("session_extend: Extending", { additionalMs: params.additionalMs });
-    const session = sessionManager.getCurrentSession();
-    if (!session) {
+    const result = core.sessionExtend(params.additionalMs);
+    if (!result.ok) {
         logger.warn("session_extend: No active session");
         return { content: [{ type: "text", text: "No active session" }] };
     }
-    sessionManager.extendSession(session.sessionId, params.additionalMs);
-    const newExpiry = sessionManager.getTimeRemaining(session.sessionId);
-    logger.info("session_extend: Extended", { sessionId: session.sessionId, newExpiry });
+    logger.info("session_extend: Extended", { newExpiry: result.data.newExpiry });
+    // Preserve the original plain content shape (not via createToolResult).
     return {
         content: [
             {
                 type: "text",
-                text: `Session extended by ${params.additionalMs / 1000}s. New expiry: ${Math.round(newExpiry / 1000)}s`,
+                text: result.text,
             },
         ],
     };
@@ -678,97 +657,32 @@ registerAppTool(server, "find", {
         timeout: z.number().optional().describe("Timeout in ms for polling"),
     }),
     _meta: { ui: { resourceUri: RESOURCE_URI, expanded: true } },
-}, async (params) => {
+}, async (params, extra) => {
     const startTime = Date.now();
+    const progress = makeProgressReporter(extra);
     logger.info("find: Starting", { description: params.description, timeout: params.timeout });
-    const sessionCheck = requireActiveSession();
-    if (!sessionCheck.valid) {
-        logger.warn("find: No active session");
-        return sessionCheck.error;
-    }
     try {
         logger.debug("find: Calling SDK find");
-        const element = await sdk.find(params.description, params.timeout ? { timeout: params.timeout } : undefined);
-        const found = element.found();
-        const coords = element.getCoordinates();
-        // Store element ref for later use (stores actual Element instance)
-        const elementRef = `el-${Date.now()}`;
-        if (found && coords) {
-            elementRefs.set(elementRef, {
-                element: element, // Store the actual Element instance
-                description: params.description,
-                coords: {
-                    x: coords.x,
-                    y: coords.y,
-                    centerX: coords.centerX,
-                    centerY: coords.centerY,
-                },
-            });
-            logger.info("find: Element found", {
-                description: params.description,
-                coords: { x: coords.centerX, y: coords.centerY },
-                confidence: element.confidence,
-                elementRef
-            });
+        const stopHeartbeat = progress.heartbeat(`Looking for "${params.description}"...`);
+        let result;
+        try {
+            result = await raceAbort(extra.signal, "find", core.find(params.description, params.timeout));
         }
-        else {
-            logger.warn("find: Element not found", { description: params.description });
+        finally {
+            stopHeartbeat();
         }
-        // Return raw SDK response directly
-        const rawResponse = element._response || {};
         const duration = Date.now() - startTime;
-        // Store cropped image for resource serving (instead of inline data URL)
-        let croppedImageResourceUri;
-        let screenshotResourceUri;
-        const croppedImage = rawResponse.croppedImage;
-        if (croppedImage) {
-            const imageData = croppedImage.startsWith('data:')
-                ? croppedImage.replace(/^data:image\/\w+;base64,/, '')
-                : croppedImage;
-            croppedImageResourceUri = storeImage(imageData, "cropped");
-            // Remove croppedImage from response to avoid context bloat
-            delete rawResponse.croppedImage;
-        }
-        else if (!found) {
-            // Element not found and no cropped image - capture a fresh screenshot
-            // so the user can see what's currently visible on screen
-            try {
-                const screenshotBase64 = await sdk.agent.system.captureScreenBase64(1, false, true);
-                if (screenshotBase64) {
-                    screenshotResourceUri = storeImage(screenshotBase64, "screenshot");
-                    logger.debug("find: Captured screenshot for not-found state");
-                }
-            }
-            catch (e) {
-                logger.warn("find: Failed to capture screenshot for not-found state", { error: String(e) });
-            }
-        }
-        // Remove extractedText and pixelDiffImage from response to reduce context bloat
-        delete rawResponse.extractedText;
-        delete rawResponse.pixelDiffImage;
-        // Generate code for this find action
-        const generatedCode = found ? generateActionCode("find", { description: params.description }) : undefined;
-        // Build element info for display (cropped image is always centered on element)
-        const elementInfo = found ? {
-            description: params.description,
-            centerX: coords?.centerX,
-            centerY: coords?.centerY,
-            confidence: element.confidence,
-            ref: elementRef,
-        } : undefined;
-        return createToolResult(found, found
-            ? `Found: "${params.description}" at (${rawResponse.coordinates?.x}, ${rawResponse.coordinates?.y})\nRef: ${elementRef}`
-            : `Element not found: "${params.description}"`, {
-            ...rawResponse,
-            action: "find",
-            element: elementInfo,
-            ref: elementRef,
-            croppedImageResourceUri,
-            screenshotResourceUri,
-            duration,
-        }, generatedCode);
+        logger.info("find: Completed", { description: params.description, found: result.ok, duration });
+        return resultToMcp({ ...result, data: { ...result.data, duration } });
     }
     catch (error) {
+        if (error instanceof NoActiveSessionError) {
+            logger.warn("find: No active session");
+            return noSessionResult(error);
+        }
+        const cancelled = cancelledResultOrNull(error, "find");
+        if (cancelled)
+            return cancelled;
         logger.error("find: Failed", { error: String(error), description: params.description });
         captureException(error, { tags: { tool: "find" }, extra: { description: params.description } });
         throw error;
@@ -783,101 +697,32 @@ registerAppTool(server, "findall", {
         timeout: z.number().optional().describe("Timeout in ms for polling"),
     }),
     _meta: { ui: { resourceUri: RESOURCE_URI, expanded: true } },
-}, async (params) => {
+}, async (params, extra) => {
     const startTime = Date.now();
+    const progress = makeProgressReporter(extra);
     logger.info("findall: Starting", { description: params.description, timeout: params.timeout });
-    const sessionCheck = requireActiveSession();
-    if (!sessionCheck.valid) {
-        logger.warn("findall: No active session");
-        return sessionCheck.error;
-    }
     try {
         logger.debug("findall: Calling SDK findAll");
-        const elements = await sdk.findAll(params.description, params.timeout ? { timeout: params.timeout } : undefined);
-        const count = elements.length;
-        // Store element refs for later use
-        const refs = [];
-        const elementInfos = [];
-        for (let i = 0; i < elements.length; i++) {
-            const element = elements[i];
-            const coords = element.getCoordinates();
-            const elementRef = `el-${Date.now()}-${i}`;
-            if (coords) {
-                elementRefs.set(elementRef, {
-                    element: element,
-                    description: `${params.description} [${i}]`,
-                    coords: {
-                        x: coords.x,
-                        y: coords.y,
-                        centerX: coords.centerX,
-                        centerY: coords.centerY,
-                    },
-                });
-                refs.push(elementRef);
-                elementInfos.push({
-                    ref: elementRef,
-                    x: coords.x,
-                    y: coords.y,
-                    centerX: coords.centerX,
-                    centerY: coords.centerY,
-                    confidence: element.confidence,
-                });
-            }
-        }
-        logger.info("findall: Elements found", {
-            description: params.description,
-            count,
-            refs
-        });
-        // Get the first element's response for the image (shows all highlights)
-        const rawResponse = elements[0]?._response || {};
-        const duration = Date.now() - startTime;
-        // Store cropped image for resource serving (instead of inline data URL)
-        let croppedImageResourceUri;
-        let screenshotResourceUri;
-        const croppedImage = rawResponse.croppedImage;
-        if (croppedImage) {
-            const imageData = croppedImage.startsWith('data:')
-                ? croppedImage.replace(/^data:image\/\w+;base64,/, '')
-                : croppedImage;
-            croppedImageResourceUri = storeImage(imageData, "cropped");
-            // Remove croppedImage from response to avoid context bloat
-            delete rawResponse.croppedImage;
+        const stopHeartbeat = progress.heartbeat(`Looking for all "${params.description}"...`);
+        let result;
+        try {
+            result = await raceAbort(extra.signal, "findall", core.findAll(params.description, params.timeout));
         }
-        else if (count === 0) {
-            // No elements found and no cropped image - capture a fresh screenshot
-            // so the user can see what's currently visible on screen
-            try {
-                const screenshotBase64 = await sdk.agent.system.captureScreenBase64(1, false, true);
-                if (screenshotBase64) {
-                    screenshotResourceUri = storeImage(screenshotBase64, "screenshot");
-                    logger.debug("findall: Captured screenshot for not-found state");
-                }
-            }
-            catch (e) {
-                logger.warn("findall: Failed to capture screenshot for not-found state", { error: String(e) });
-            }
+        finally {
+            stopHeartbeat();
         }
-        // Remove extractedText and pixelDiffImage from response to reduce context bloat
-        delete rawResponse.extractedText;
-        delete rawResponse.pixelDiffImage;
-        // Generate code for this findall action
-        const generatedCode = count > 0 ? generateActionCode("findall", { description: params.description }) : undefined;
-        // Build refs list for text output
-        const refsList = refs.map((ref, i) => `  [${i}] ${ref}`).join('\n');
-        return createToolResult(count > 0, count > 0
-            ? `Found ${count} elements matching "${params.description}":\n${refsList}`
-            : `No elements found matching: "${params.description}"`, {
-            ...rawResponse,
-            count,
-            refs,
-            elements: elementInfos,
-            croppedImageResourceUri,
-            screenshotResourceUri,
-            duration,
-        }, generatedCode);
+        const duration = Date.now() - startTime;
+        logger.info("findall: Completed", { description: params.description, count: result.data.count, duration });
+        return resultToMcp({ ...result, data: { ...result.data, duration } });
     }
     catch (error) {
+        if (error instanceof NoActiveSessionError) {
+            logger.warn("findall: No active session");
+            return noSessionResult(error);
+        }
+        const cancelled = cancelledResultOrNull(error, "findall");
+        if (cancelled)
+            return cancelled;
         logger.error("findall: Failed", { error: String(error), description: params.description });
         captureException(error, { tags: { tool: "findall" }, extra: { description: params.description } });
         throw error;
@@ -895,58 +740,19 @@ registerAppTool(server, "click", {
 }, async (params) => {
     const startTime = Date.now();
     logger.info("click: Starting", { elementRef: params.elementRef, action: params.action });
-    const sessionCheck = requireActiveSession();
-    if (!sessionCheck.valid) {
-        logger.warn("click: No active session");
-        return sessionCheck.error;
-    }
-    // Look up the element reference
-    const ref = elementRefs.get(params.elementRef);
-    if (!ref) {
-        logger.warn("click: Element reference not found", { elementRef: params.elementRef });
-        return createToolResult(false, `Element reference "${params.elementRef}" not found. Use 'find' first to locate the element.`, { error: "Element reference not found" });
-    }
-    const { element, description, coords } = ref;
     try {
-        logger.debug("click: Executing click on element", { description, action: params.action });
-        // Use the Element's click method instead of raw coordinates
-        if (params.action === "click") {
-            await element.click();
-        }
-        else if (params.action === "double-click") {
-            await element.doubleClick();
-        }
-        else if (params.action === "right-click") {
-            await element.rightClick();
-        }
-        // Capture screenshot after click to show result
-        logger.debug("click: Capturing screenshot after click");
-        const screenshotBase64 = await sdk.agent.system.captureScreenBase64(1, false, true);
-        let screenshotResourceUri;
-        if (screenshotBase64) {
-            screenshotResourceUri = storeImage(screenshotBase64, "screenshot");
-            lastScreenshotBase64 = screenshotBase64;
-        }
-        const rawResponse = element._response || {};
-        // Remove large data from response to reduce context bloat
-        delete rawResponse.croppedImage;
-        delete rawResponse.extractedText;
-        delete rawResponse.pixelDiffImage;
+        logger.debug("click: Executing click on element", { elementRef: params.elementRef, action: params.action });
+        const result = await core.click(params.elementRef, params.action);
         const duration = Date.now() - startTime;
-        logger.info("click: Completed", { description, duration });
-        // Generate code for this click action
-        const generatedCode = generateActionCode("click", { action: params.action });
-        return createToolResult(true, `Clicked on "${description}"`, {
-            ...rawResponse,
-            action: "click",
-            clickAction: params.action,
-            clickPosition: coords,
-            screenshotResourceUri,
-            duration
-        }, generatedCode);
+        logger.info("click: Completed", { elementRef: params.elementRef, duration });
+        return resultToMcp({ ...result, data: { ...result.data, duration } });
     }
     catch (error) {
-        logger.error("click: Failed", { error: String(error), description });
+        if (error instanceof NoActiveSessionError) {
+            logger.warn("click: No active session");
+            return noSessionResult(error);
+        }
+        logger.error("click: Failed", { error: String(error), elementRef: params.elementRef });
         captureException(error, { tags: { tool: "click" }, extra: { elementRef: params.elementRef, action: params.action } });
         throw error;
     }
@@ -962,47 +768,19 @@ registerAppTool(server, "hover", {
 }, async (params) => {
     const startTime = Date.now();
     logger.info("hover: Starting", { elementRef: params.elementRef });
-    const sessionCheck = requireActiveSession();
-    if (!sessionCheck.valid) {
-        logger.warn("hover: No active session");
-        return sessionCheck.error;
-    }
-    // Look up the element reference
-    const ref = elementRefs.get(params.elementRef);
-    if (!ref) {
-        logger.warn("hover: Element reference not found", { elementRef: params.elementRef });
-        return createToolResult(false, `Element reference "${params.elementRef}" not found. Use 'find' first to locate the element.`, { error: "Element reference not found" });
-    }
-    const { element, description, coords } = ref;
     try {
-        logger.debug("hover: Executing hover on element", { description });
-        await element.hover();
-        // Capture screenshot after hover to show result
-        logger.debug("hover: Capturing screenshot after hover");
-        const screenshotBase64 = await sdk.agent.system.captureScreenBase64(1, false, true);
-        let screenshotResourceUri;
-        if (screenshotBase64) {
-            screenshotResourceUri = storeImage(screenshotBase64, "screenshot");
-            lastScreenshotBase64 = screenshotBase64;
-        }
-        const rawResponse = element._response || {};
-        // Remove large data from response to reduce context bloat
-        delete rawResponse.croppedImage;
-        delete rawResponse.extractedText;
-        delete rawResponse.pixelDiffImage;
+        logger.debug("hover: Executing hover on element", { elementRef: params.elementRef });
+        const result = await core.hover(params.elementRef);
         const duration = Date.now() - startTime;
-        logger.info("hover: Completed", { description, duration });
-        // Generate code for this hover action
-        const generatedCode = generateActionCode("hover", {});
-        return createToolResult(true, `Hovered over "${description}"`, {
-            ...rawResponse,
-            action: "hover",
-            screenshotResourceUri,
-            duration
-        }, generatedCode);
+        logger.info("hover: Completed", { elementRef: params.elementRef, duration });
+        return resultToMcp({ ...result, data: { ...result.data, duration } });
     }
     catch (error) {
-        logger.error("hover: Failed", { error: String(error), description });
+        if (error instanceof NoActiveSessionError) {
+            logger.warn("hover: No active session");
+            return noSessionResult(error);
+        }
+        logger.error("hover: Failed", { error: String(error), elementRef: params.elementRef });
         captureException(error, { tags: { tool: "hover" }, extra: { elementRef: params.elementRef } });
         throw error;
     }
@@ -1016,21 +794,18 @@ server.registerTool("wait", {
 }, async (params) => {
     const startTime = Date.now();
     logger.info("wait: Starting", { timeout: params.timeout });
-    const sessionCheck = requireActiveSession();
-    if (!sessionCheck.valid) {
-        logger.warn("wait: No active session");
-        return sessionCheck.error;
-    }
     try {
         logger.debug("wait: Waiting", { timeout: params.timeout });
-        await sdk.wait(params.timeout);
+        const result = await core.wait(params.timeout);
         const duration = Date.now() - startTime;
         logger.info("wait: Completed", { timeout: params.timeout, duration });
-        // Generate code for this wait action
-        const generatedCode = generateActionCode("wait", { timeout: params.timeout });
-        return createToolResult(true, `Waited for ${params.timeout}ms`, { action: "wait", timeout: params.timeout, duration }, generatedCode);
+        return resultToMcp({ ...result, data: { ...result.data, duration } });
     }
     catch (error) {
+        if (error instanceof NoActiveSessionError) {
+            logger.warn("wait: No active session");
+            return noSessionResult(error);
+        }
         logger.error("wait: Failed", { error: String(error) });
         captureException(error, { tags: { tool: "wait" }, extra: { timeout: params.timeout } });
         throw error;
@@ -1045,21 +820,18 @@ server.registerTool("focus_application", {
 }, async (params) => {
     const startTime = Date.now();
     logger.info("focus_application: Starting", { name: params.name });
-    const sessionCheck = requireActiveSession();
-    if (!sessionCheck.valid) {
-        logger.warn("focus_application: No active session");
-        return sessionCheck.error;
-    }
     try {
         logger.debug("focus_application: Focusing", { name: params.name });
-        await sdk.focusApplication(params.name);
+        const result = await core.focusApplication(params.name);
         const duration = Date.now() - startTime;
         logger.info("focus_application: Completed", { name: params.name, duration });
-        // Generate code for this focus action
-        const generatedCode = generateActionCode("focus_application", { name: params.name });
-        return createToolResult(true, `Focused application: "${params.name}"`, { action: "focus", name: params.name, duration }, generatedCode);
+        return resultToMcp({ ...result, data: { ...result.data, duration } });
     }
     catch (error) {
+        if (error instanceof NoActiveSessionError) {
+            logger.warn("focus_application: No active session");
+            return noSessionResult(error);
+        }
         logger.error("focus_application: Failed", { error: String(error), name: params.name });
         captureException(error, { tags: { tool: "focus_application" }, extra: { name: params.name } });
         throw error;
@@ -1074,124 +846,32 @@ registerAppTool(server, "find_and_click", {
         action: z.enum(["click", "double-click", "right-click"]).default("click"),
     }),
     _meta: { ui: { resourceUri: RESOURCE_URI, expanded: true } },
-}, async (params) => {
+}, async (params, extra) => {
     const startTime = Date.now();
+    const progress = makeProgressReporter(extra);
     logger.info("find_and_click: Starting", { description: params.description, action: params.action });
-    const sessionCheck = requireActiveSession();
-    if (!sessionCheck.valid) {
-        logger.warn("find_and_click: No active session");
-        return sessionCheck.error;
-    }
     try {
         logger.debug("find_and_click: Finding element");
-        const element = await sdk.find(params.description);
-        const found = element.found();
-        if (!found) {
-            logger.warn("find_and_click: Element not found", { description: params.description });
-            // Capture screenshot to show current state even when element not found
-            const rawResponse = element._response || {};
-            const duration = Date.now() - startTime;
-            // Store cropped image (screenshot) for resource serving
-            let croppedImageResourceUri;
-            let screenshotResourceUri;
-            const croppedImage = rawResponse.croppedImage;
-            if (croppedImage) {
-                const imageData = croppedImage.startsWith('data:')
-                    ? croppedImage.replace(/^data:image\/\w+;base64,/, '')
-                    : croppedImage;
-                croppedImageResourceUri = storeImage(imageData, "screenshot");
-                delete rawResponse.croppedImage;
-            }
-            else {
-                // No cropped image - capture a fresh screenshot so the user can see
-                // what's currently visible on screen when element was not found
-                try {
-                    const screenshotBase64 = await sdk.agent.system.captureScreenBase64(1, false, true);
-                    if (screenshotBase64) {
-                        screenshotResourceUri = storeImage(screenshotBase64, "screenshot");
-                        logger.debug("find_and_click: Captured screenshot for not-found state");
-                    }
-                }
-                catch (e) {
-                    logger.warn("find_and_click: Failed to capture screenshot for not-found state", { error: String(e) });
-                }
-            }
-            // Remove extractedText and pixelDiffImage from response to reduce context bloat
-            delete rawResponse.extractedText;
-            delete rawResponse.pixelDiffImage;
-            return createToolResult(false, `Element not found: "${params.description}"`, {
-                ...rawResponse,
-                action: "find_and_click",
-                error: "Element not found",
-                croppedImageResourceUri,
-                screenshotResourceUri,
-                duration
-            });
+        const stopHeartbeat = progress.heartbeat(`Looking for "${params.description}"...`);
+        let result;
+        try {
+            result = await raceAbort(extra.signal, "find_and_click", core.findAndClick(params.description, params.action));
         }
-        const coords = element.getCoordinates();
-        // Store element ref for later use (in case user wants to interact again)
-        const elementRef = `el-${Date.now()}`;
-        if (coords) {
-            elementRefs.set(elementRef, {
-                element: element,
-                description: params.description,
-                coords: {
-                    x: coords.x,
-                    y: coords.y,
-                    centerX: coords.centerX,
-                    centerY: coords.centerY,
-                },
-            });
+        finally {
+            stopHeartbeat();
         }
-        logger.debug("find_and_click: Element found, clicking", { action: params.action, elementRef });
-        if (params.action === "click") {
-            await element.click();
-        }
-        else if (params.action === "double-click") {
-            await element.doubleClick();
-        }
-        else if (params.action === "right-click") {
-            await element.rightClick();
-        }
-        // Return raw SDK response directly
-        const rawResponse = element._response || {};
         const duration = Date.now() - startTime;
-        // Store cropped image for resource serving (instead of inline data URL)
-        let croppedImageResourceUri;
-        const croppedImage = rawResponse.croppedImage;
-        if (croppedImage) {
-            const imageData = croppedImage.startsWith('data:')
-                ? croppedImage.replace(/^data:image\/\w+;base64,/, '')
-                : croppedImage;
-            croppedImageResourceUri = storeImage(imageData, "cropped");
-            // Remove croppedImage from response to avoid context bloat
-            delete rawResponse.croppedImage;
-        }
-        // Remove extractedText and pixelDiffImage from response to reduce context bloat
-        delete rawResponse.extractedText;
-        delete rawResponse.pixelDiffImage;
-        // Generate code for this find_and_click action
-        const generatedCode = generateActionCode("find_and_click", { description: params.description, action: params.action });
-        // Build element info for display (match find action format)
-        const elementInfo = coords ? {
-            description: params.description,
-            centerX: coords.centerX,
-            centerY: coords.centerY,
-            confidence: element.confidence,
-            ref: elementRef,
-        } : undefined;
-        return createToolResult(true, `Found and clicked: "${params.description}" at (${rawResponse.coordinates?.x}, ${rawResponse.coordinates?.y})\nRef: ${elementRef}`, {
-            ...rawResponse,
-            action: "find_and_click",
-            element: elementInfo,
-            ref: elementRef,
-            clickAction: params.action,
-            clickPosition: coords ? { x: coords.centerX, y: coords.centerY } : undefined,
-            croppedImageResourceUri,
-            duration,
-        }, generatedCode);
+        logger.info("find_and_click: Completed", { description: params.description, found: result.ok, duration });
+        return resultToMcp({ ...result, data: { ...result.data, duration } });
     }
     catch (error) {
+        if (error instanceof NoActiveSessionError) {
+            logger.warn("find_and_click: No active session");
+            return noSessionResult(error);
+        }
+        const cancelled = cancelledResultOrNull(error, "find_and_click");
+        if (cancelled)
+            return cancelled;
         logger.error("find_and_click: Failed", { error: String(error), description: params.description });
         captureException(error, { tags: { tool: "find_and_click" }, extra: { description: params.description, action: params.action } });
         throw error;
@@ -1208,21 +888,18 @@ server.registerTool("type", {
 }, async (params) => {
     const startTime = Date.now();
     logger.info("type: Starting", { textLength: params.text.length, secret: params.secret });
-    const sessionCheck = requireActiveSession();
-    if (!sessionCheck.valid) {
-        logger.warn("type: No active session");
-        return sessionCheck.error;
-    }
     try {
         logger.debug("type: Typing text");
-        await sdk.type(params.text, { secret: params.secret, delay: params.delay });
+        const result = await core.type(params.text, params.secret, params.delay);
         const duration = Date.now() - startTime;
         logger.info("type: Completed", { duration });
-        // Generate code for this type action
-        const generatedCode = generateActionCode("type", { text: params.text, secret: params.secret });
-        return createToolResult(true, `Typed: ${params.secret ? "[secret text]" : `"${params.text}"`}`, { action: "type", text: params.secret ? "[SECRET]" : params.text, duration }, generatedCode);
+        return resultToMcp({ ...result, data: { ...result.data, duration } });
     }
     catch (error) {
+        if (error instanceof NoActiveSessionError) {
+            logger.warn("type: No active session");
+            return noSessionResult(error);
+        }
         logger.error("type: Failed", { error: String(error) });
         captureException(error, { tags: { tool: "type" }, extra: { textLength: params.text.length, secret: params.secret } });
         throw error;
@@ -1237,21 +914,18 @@ server.registerTool("press_keys", {
 }, async (params) => {
     const startTime = Date.now();
     logger.info("press_keys: Starting", { keys: params.keys });
-    const sessionCheck = requireActiveSession();
-    if (!sessionCheck.valid) {
-        logger.warn("press_keys: No active session");
-        return sessionCheck.error;
-    }
     try {
         logger.debug("press_keys: Pressing keys");
-        await sdk.pressKeys(params.keys);
+        const result = await core.pressKeys(params.keys);
         const duration = Date.now() - startTime;
         logger.info("press_keys: Completed", { keys: params.keys, duration });
-        // Generate code for this press_keys action
-        const generatedCode = generateActionCode("press_keys", { keys: params.keys });
-        return createToolResult(true, `Pressed keys: ${params.keys.join(" + ")}`, { action: "press_keys", keys: params.keys, duration }, generatedCode);
+        return resultToMcp({ ...result, data: { ...result.data, duration } });
     }
     catch (error) {
+        if (error instanceof NoActiveSessionError) {
+            logger.warn("press_keys: No active session");
+            return noSessionResult(error);
+        }
         logger.error("press_keys: Failed", { error: String(error), keys: params.keys });
         captureException(error, { tags: { tool: "press_keys" }, extra: { keys: params.keys } });
         throw error;
@@ -1267,21 +941,18 @@ server.registerTool("scroll", {
 }, async (params) => {
     const startTime = Date.now();
     logger.info("scroll: Starting", { direction: params.direction, amount: params.amount });
-    const sessionCheck = requireActiveSession();
-    if (!sessionCheck.valid) {
-        logger.warn("scroll: No active session");
-        return sessionCheck.error;
-    }
     try {
         logger.debug("scroll: Scrolling");
-        await sdk.scroll(params.direction, params.amount ? { amount: params.amount } : undefined);
+        const result = await core.scroll(params.direction, params.amount);
         const duration = Date.now() - startTime;
         logger.info("scroll: Completed", { direction: params.direction, duration });
-        // Generate code for this scroll action
-        const generatedCode = generateActionCode("scroll", { direction: params.direction, amount: params.amount });
-        return createToolResult(true, `Scrolled ${params.direction}${params.amount ? ` by ${params.amount}px` : ""}`, { action: "scroll", scrollDirection: params.direction, direction: params.direction, amount: params.amount, duration }, generatedCode);
+        return resultToMcp({ ...result, data: { ...result.data, duration } });
     }
     catch (error) {
+        if (error instanceof NoActiveSessionError) {
+            logger.warn("scroll: No active session");
+            return noSessionResult(error);
+        }
         logger.error("scroll: Failed", { error: String(error), direction: params.direction });
         captureException(error, { tags: { tool: "scroll" }, extra: { direction: params.direction, amount: params.amount } });
         throw error;
@@ -1302,21 +973,18 @@ Unlike 'check' which is for your understanding during development, 'assert' crea
 }, async (params) => {
     const startTime = Date.now();
     logger.info("assert: Starting", { assertion: params.assertion });
-    const sessionCheck = requireActiveSession();
-    if (!sessionCheck.valid) {
-        logger.warn("assert: No active session");
-        return sessionCheck.error;
-    }
     try {
         logger.debug("assert: Running assertion");
-        const result = await sdk.assert(params.assertion);
+        const result = await core.assert(params.assertion);
         const duration = Date.now() - startTime;
-        logger.info("assert: Completed", { assertion: params.assertion, passed: result, duration });
-        // Generate code for this assert action
-        const generatedCode = generateActionCode("assert", { assertion: params.assertion });
-        return createToolResult(result, result ? `✓ Assertion passed: "${params.assertion}"` : `✗ Assertion failed: "${params.assertion}"`, { action: "assert", assertion: params.assertion, passed: result, success: result, duration }, generatedCode);
+        logger.info("assert: Completed", { assertion: params.assertion, passed: result.ok, duration });
+        return resultToMcp({ ...result, data: { ...result.data, duration } });
     }
     catch (error) {
+        if (error instanceof NoActiveSessionError) {
+            logger.warn("assert: No active session");
+            return noSessionResult(error);
+        }
         logger.error("assert: Failed", { error: String(error), assertion: params.assertion });
         captureException(error, { tags: { tool: "assert" }, extra: { assertion: params.assertion } });
         throw error;
@@ -1349,29 +1017,24 @@ You can optionally provide a reference image URI to compare against a previous s
         referenceImageUri: z.string().optional().describe("Optional screenshot resource URI (e.g., 'screenshot://testdriver/screenshot/screenshot-1') to compare against instead of the automatically captured 'before' screenshot. Use a screenshotResourceUri from a previous action."),
     }),
     _meta: { ui: { resourceUri: RESOURCE_URI, expanded: true } },
-}, async (params) => {
+}, async (params, extra) => {
     const startTime = Date.now();
+    const progress = makeProgressReporter(extra);
     logger.info("check: Starting", { task: params.task, hasReferenceImageUri: !!params.referenceImageUri });
-    const sessionCheck = requireActiveSession();
-    if (!sessionCheck.valid) {
-        logger.warn("check: No active session");
-        return sessionCheck.error;
-    }
     try {
-        // Capture current screenshot
-        logger.debug("check: Capturing current screenshot");
-        const currentScreenshot = await sdk.agent.system.captureScreenBase64(1, false, true);
-        // Use provided reference image URI, last screenshot as "before" state, or current if no previous screenshot
-        let beforeScreenshot;
+        // Resolve the optional reference image from the image store (a server/UI
+        // concern). The core handles "last screenshot" / current-screenshot
+        // fallback internally when no reference image is passed.
+        let referenceImage;
         if (params.referenceImageUri) {
             // Extract image ID from URI (e.g., "screenshot://testdriver/screenshot/screenshot-1" -> "screenshot-1")
-            const uriParts = params.referenceImageUri.split('/');
+            const uriParts = params.referenceImageUri.split("/");
             const imageId = uriParts[uriParts.length - 1];
             logger.info("check: Looking up reference image", {
                 referenceImageUri: params.referenceImageUri,
                 extractedImageId: imageId,
                 imageStoreSize: imageStore.size,
-                availableKeys: Array.from(imageStore.keys())
+                availableKeys: Array.from(imageStore.keys()),
             });
             const storedImage = getStoredImage(imageId);
             if (storedImage) {
@@ -1379,72 +1042,40 @@ You can optionally provide a reference image URI to compare against a previous s
                     imageId,
                     dataLength: storedImage.data?.length,
                     type: storedImage.type,
-                    hasData: !!storedImage.data
+                    hasData: !!storedImage.data,
                 });
-                beforeScreenshot = storedImage.data;
+                referenceImage = storedImage.data;
             }
             else {
                 logger.warn("check: Reference image NOT found in store, falling back to last screenshot", {
                     referenceImageUri: params.referenceImageUri,
                     imageId,
                     imageStoreSize: imageStore.size,
-                    availableKeys: Array.from(imageStore.keys())
+                    availableKeys: Array.from(imageStore.keys()),
                 });
-                beforeScreenshot = lastScreenshotBase64 || currentScreenshot;
             }
         }
-        else {
-            beforeScreenshot = lastScreenshotBase64 || currentScreenshot;
+        progress.report("Capturing screenshot...");
+        const stopHeartbeat = progress.heartbeat(`Checking: "${params.task}"...`);
+        let result;
+        try {
+            result = await raceAbort(extra.signal, "check", core.check(params.task, referenceImage));
         }
-        // Update last screenshot for next check
-        lastScreenshotBase64 = currentScreenshot;
-        // Get system state
-        const mousePosition = await sdk.agent.system.getMousePosition();
-        const activeWindow = await sdk.agent.system.activeWin();
-        // Call the check endpoint
-        logger.info("check: Calling check API endpoint", {
-            hasLastScreenshot: beforeScreenshot !== currentScreenshot,
-            usingReferenceImageUri: !!params.referenceImageUri,
-            beforeScreenshotLength: beforeScreenshot?.length || 0,
-            currentScreenshotLength: currentScreenshot?.length || 0,
-            beforeScreenshotPreview: beforeScreenshot?.substring(0, 50),
-            currentScreenshotPreview: currentScreenshot?.substring(0, 50)
-        });
-        const response = await sdk.agent.sdk.req("check", {
-            tasks: [params.task],
-            images: [beforeScreenshot, currentScreenshot],
-            mousePosition,
-            activeWindow,
-        });
-        const aiResponse = response.data;
-        // Store screenshot for resource serving
-        let screenshotResourceUri;
-        if (currentScreenshot) {
-            screenshotResourceUri = storeImage(currentScreenshot, "screenshot");
+        finally {
+            stopHeartbeat();
         }
-        // Determine if the check passed based on the AI response
-        // The AI typically returns markdown with its analysis
-        // We consider it "complete" if the response doesn't contain code blocks (indicating more work needed)
-        const hasCodeBlocks = aiResponse && (aiResponse.includes("```yml") ||
-            aiResponse.includes("```yaml") ||
-            aiResponse.includes("- command:"));
-        const isComplete = !hasCodeBlocks;
         const duration = Date.now() - startTime;
-        logger.info("check: Completed", { task: params.task, complete: isComplete, duration });
-        // Note: check doesn't generate code - it's for AI understanding, not test recording
-        return createToolResult(isComplete, isComplete
-            ? `✓ Task appears complete: "${params.task}"\n\nAI Analysis:\n${aiResponse}`
-            : `⚠ Task may not be complete: "${params.task}"\n\nAI Analysis:\n${aiResponse}`, {
-            action: "check",
-            task: params.task,
-            complete: isComplete,
-            success: isComplete,
-            aiResponse,
-            screenshotResourceUri,
-            duration
-        });
+        logger.info("check: Completed", { task: params.task, complete: result.ok, duration });
+        return resultToMcp({ ...result, data: { ...result.data, duration } });
     }
     catch (error) {
+        if (error instanceof NoActiveSessionError) {
+            logger.warn("check: No active session");
+            return noSessionResult(error);
+        }
+        const cancelled = cancelledResultOrNull(error, "check");
+        if (cancelled)
+            return cancelled;
         logger.error("check: Failed", { error: String(error), task: params.task });
         captureException(error, { tags: { tool: "check" }, extra: { task: params.task } });
         throw error;
@@ -1461,21 +1092,18 @@ server.registerTool("exec", {
 }, async (params) => {
     const startTime = Date.now();
     logger.info("exec: Starting", { language: params.language, codeLength: params.code.length, timeout: params.timeout });
-    const sessionCheck = requireActiveSession();
-    if (!sessionCheck.valid) {
-        logger.warn("exec: No active session");
-        return sessionCheck.error;
-    }
     try {
         logger.debug("exec: Executing code", { language: params.language });
-        const output = await sdk.exec(params.language, params.code, params.timeout);
+        const result = await core.exec(params.language, params.code, params.timeout);
         const duration = Date.now() - startTime;
-        logger.info("exec: Completed", { language: params.language, outputLength: output?.length || 0, duration });
-        // Generate code for this exec action
-        const generatedCode = generateActionCode("exec", { language: params.language, code: params.code, timeout: params.timeout });
-        return createToolResult(true, `Executed ${params.language} code:\n${output || "(no output)"}`, { action: "exec", language: params.language, output, duration }, generatedCode);
+        logger.info("exec: Completed", { language: params.language, outputLength: result.data.output?.length || 0, duration });
+        return resultToMcp({ ...result, data: { ...result.data, duration } });
     }
     catch (error) {
+        if (error instanceof NoActiveSessionError) {
+            logger.warn("exec: No active session");
+            return noSessionResult(error);
+        }
         logger.error("exec: Failed", { error: String(error), language: params.language });
         captureException(error, { tags: { tool: "exec" }, extra: { language: params.language, codeLength: params.code.length } });
         throw error;
@@ -1811,30 +1439,25 @@ Only use 'screenshot' when you explicitly want to show something to the human us
 }, async () => {
     const startTime = Date.now();
     logger.info("screenshot: Starting");
-    const sessionCheck = requireActiveSession();
-    if (!sessionCheck.valid) {
-        logger.warn("screenshot: No active session");
-        return sessionCheck.error;
-    }
     try {
-        // Capture full screen screenshot
-        const screenshotBase64 = await sdk.agent.system.captureScreenBase64(1, false, true);
-        let screenshotResourceUri;
-        if (screenshotBase64) {
-            // Store raw base64 for the resource blob with unique ID
-            screenshotResourceUri = storeImage(screenshotBase64, "screenshot");
+        const result = await core.screenshot();
+        // Store the captured image as a resource URI (kept OUT of AI context — the
+        // MCP app fetches it via resources/read). Preserve the original user-facing
+        // text rather than the core's neutral text.
+        const data = { action: "screenshot" };
+        for (const img of result.images ?? []) {
+            data.screenshotResourceUri = storeImage(img.base64, "screenshot");
         }
         const duration = Date.now() - startTime;
-        logger.info("screenshot: Completed", { duration, hasImage: !!screenshotBase64 });
-        // Only send the resource URI - the MCP app will fetch the image via resources/read
-        // This keeps the base64 image data OUT of AI context
-        return createToolResult(true, "Screenshot captured and displayed to user", {
-            action: "screenshot",
-            screenshotResourceUri,
-            duration
-        });
+        data.duration = duration;
+        logger.info("screenshot: Completed", { duration, hasImage: (result.images?.length ?? 0) > 0 });
+        return createToolResult(true, "Screenshot captured and displayed to user", data);
     }
     catch (error) {
+        if (error instanceof NoActiveSessionError) {
+            logger.warn("screenshot: No active session");
+            return noSessionResult(error);
+        }
         logger.error("screenshot: Failed", { error: String(error) });
         return createToolResult(false, `Screenshot failed: ${error}`, { error: String(error) });
     }
@@ -1860,6 +1483,7 @@ API Key: The apiKey parameter is optional. If not provided, you'll need to manua
         directory: z.string().optional().describe("Target directory (defaults to current working directory)"),
         apiKey: z.string().optional().describe("TestDriver API key (will be saved to .env)"),
         skipInstall: z.boolean().default(false).describe("Skip npm install step"),
+        skipSampleTest: z.boolean().default(false).describe("Skip scaffolding the example test files (tests/example.test.js + tests/login.js). Useful when an agent writes its own tests."),
     }),
 }, async (params) => {
     const startTime = Date.now();
@@ -1874,6 +1498,7 @@ API Key: The apiKey parameter is optional. If not provided, you'll need to manua
             targetDir,
             apiKey: params.apiKey,
             skipInstall: params.skipInstall,
+            skipSampleTest: params.skipSampleTest,
         });
         const duration = Date.now() - startTime;
         logger.info("init: Completed", { targetDir, duration, success: result.success });
@@ -1913,14 +1538,87 @@ Learn more at https://docs.testdriver.ai/v7/getting-started/
         throw error;
     }
 });
+// =============================================================================
+// HTTP transport (Streamable HTTP, no auth)
+// =============================================================================
+/**
+ * Serve the MCP server over Streamable HTTP with no authentication.
+ *
+ * This is what the eve agent (and any other Streamable-HTTP MCP client) connects
+ * to. The server holds single-session global state (the active `sdk`, element
+ * refs, image store), so we mirror that with a single long-lived MCP transport:
+ * the first `initialize` request mints a session id and every subsequent request
+ * reuses the same `server` + transport. Concurrent sessions are intentionally not
+ * supported — this server provisions one sandbox at a time.
+ *
+ * No auth is applied here by design (the connection is expected to be local-only
+ * or otherwise protected outside the MCP layer). Do not expose this on a public
+ * network without putting a real authenticating proxy in front of it.
+ */
+async function startHttpServer() {
+    const host = process.env.TD_MCP_HOST || "127.0.0.1";
+    const port = Number(process.env.TD_MCP_PORT || process.env.PORT || 8788);
+    const mcpPath = process.env.TD_MCP_PATH || "/mcp";
+    // One transport for the lifetime of the process (single-session design).
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+    });
+    await server.connect(transport);
+    const httpServer = http.createServer((req, res) => {
+        const url = new URL(req.url || "/", `http://${req.headers.host}`);
+        // Lightweight health check for readiness probes / `eve dev`.
+        if (req.method === "GET" && url.pathname === "/health") {
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(JSON.stringify({ status: "ok", server: "testdriver", version }));
+            return;
+        }
+        if (url.pathname !== mcpPath) {
+            res.writeHead(404, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: "Not found", hint: `MCP endpoint is ${mcpPath}` }));
+            return;
+        }
+        // The Streamable HTTP transport handles POST (requests), GET (SSE stream),
+        // and DELETE (session teardown) on the same path. Body parsing is left to
+        // the transport so it can read the raw stream.
+        transport.handleRequest(req, res).catch((error) => {
+            logger.error("http: handleRequest failed", { error: String(error) });
+            captureException(error, { tags: { phase: "http" } });
+            if (!res.headersSent) {
+                res.writeHead(500, { "content-type": "application/json" });
+                res.end(JSON.stringify({ error: "Internal server error" }));
+            }
+        });
+    });
+    await new Promise((resolve) => httpServer.listen(port, host, resolve));
+    logger.info("TestDriver MCP Server running on Streamable HTTP", {
+        url: `http://${host}:${port}${mcpPath}`,
+    });
+    const shutdown = async () => {
+        logger.info("Shutting down MCP Server");
+        httpServer.close();
+        await transport.close().catch(() => { });
+        await flushSentry();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
 // Start the server
 async function main() {
+    // Transport selection: TD_MCP_TRANSPORT=http serves Streamable HTTP (used by
+    // the eve agent); anything else (default) uses stdio for local CLI clients.
+    const transportMode = (process.env.TD_MCP_TRANSPORT || "stdio").toLowerCase();
     logger.info("Starting TestDriver MCP Server", {
         version,
+        transport: transportMode,
         logLevel: process.env.TD_LOG_LEVEL || "INFO",
         distDir: DIST_DIR,
         sentryEnabled: isSentryEnabled(),
     });
+    if (transportMode === "http") {
+        await startHttpServer();
+        return;
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
     logger.info("TestDriver MCP Server running on stdio");