preflite 1.1.0 → 1.1.3

package/dist/mcp/network-mocks/NetworkMockService.js

@@ -0,0 +1,156 @@
+import { NetworkMockServer } from "./NetworkMockServer.js";
+import { configureDeviceProxy, removeDeviceProxy, proxyHostForPlatform } from "./device-proxy.js";
+import { createServer } from "node:http";
+import { execSync } from "node:child_process";
+export class NetworkMockService {
+    server = new NetworkMockServer();
+    activeConfig = null;
+    certServer = null;
+    certServerPort = 0;
+    qrPng = null;
+    async start(config) {
+        if (this.server.getPort() > 0) {
+            await this.stop();
+        }
+        const port = await this.server.start(config.rules, "0.0.0.0", config.preferredPort ?? 0);
+        const proxyHost = proxyHostForPlatform(config.platform);
+        configureDeviceProxy({
+            platform: config.platform,
+            deviceId: config.deviceId,
+            proxyHost,
+            proxyPort: port,
+        });
+        this.activeConfig = { platform: config.platform, deviceId: config.deviceId };
+        this.startCertServer(proxyHost, port);
+        return this.server.getStats();
+    }
+    async stop() {
+        if (this.activeConfig) {
+            try {
+                removeDeviceProxy(this.activeConfig.platform, this.activeConfig.deviceId);
+            }
+            catch {
+                // best-effort cleanup
+            }
+            this.activeConfig = null;
+        }
+        this.stopCertServer();
+        await this.server.stop();
+        return this.server.getStats();
+    }
+    getCertServerUrl() {
+        if (!this.certServer || this.certServerPort === 0)
+            return null;
+        const host = proxyHostForPlatform(this.activeConfig?.platform ?? "ios");
+        return `http://${host}:${this.certServerPort}`;
+    }
+    startCertServer(proxyHost, proxyPort) {
+        this.stopCertServer();
+        const caCert = this.server.getRootCACert();
+        const mobileConfig = this.server.generateMobileConfig(proxyHost, proxyPort);
+        // Generate QR PNG using Python qrcode library
+        const qrUrl = `http://${proxyHost}:0/preflight.mobileconfig`; // port placeholder
+        this.qrPng = this.generateQrPng(qrUrl);
+        const qrPng = this.qrPng;
+        const html = this.buildCertPage(proxyHost, proxyPort);
+        this.certServer = createServer((req, res) => {
+            const url = req.url ?? "/";
+            if (url === "/" || url === "/index.html") {
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(html);
+            }
+            else if (url === "/preflight-ca.pem" && caCert) {
+                res.writeHead(200, { "Content-Type": "application/x-pem-file" });
+                res.end(caCert);
+            }
+            else if (url === "/preflight.mobileconfig" && mobileConfig) {
+                res.writeHead(200, { "Content-Type": "application/x-apple-aspen-config" });
+                res.end(mobileConfig);
+            }
+            else if (url === "/qr.png" && qrPng) {
+                res.writeHead(200, { "Content-Type": "image/png" });
+                res.end(qrPng);
+            }
+            else {
+                res.writeHead(404);
+                res.end("Not found");
+            }
+        });
+        this.certServer.listen(0, "0.0.0.0", () => {
+            const addr = this.certServer.address();
+            this.certServerPort = addr && typeof addr !== "string" ? addr.port : 0;
+            // Re-generate QR with the actual port
+            const actualUrl = `http://${proxyHost}:${this.certServerPort}/preflight.mobileconfig`;
+            this.qrPng = this.generateQrPng(actualUrl);
+        });
+    }
+    stopCertServer() {
+        if (this.certServer) {
+            this.certServer.close();
+            this.certServer = null;
+            this.certServerPort = 0;
+            this.qrPng = null;
+        }
+    }
+    generateQrPng(url) {
+        try {
+            const script = `import qrcode,sys;qrcode.make(sys.argv[1]).save('/dev/stdout')`;
+            return execSync(`python3 -c "${script}" "${url}"`, { maxBuffer: 100_000, timeout: 5000 });
+        }
+        catch {
+            return null;
+        }
+    }
+    buildCertPage(proxyHost, proxyPort) {
+        return `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>Preflight Mock</title>
+<style>
+  body { font-family: -apple-system, sans-serif; text-align: center; padding: 20px; background: #f5f5f7; }
+  .card { background: white; border-radius: 16px; padding: 24px; max-width: 400px; margin: 0 auto; box-shadow: 0 2px 12px rgba(0,0,0,0.08); }
+  h1 { font-size: 20px; margin-bottom: 4px; }
+  .sub { color: #666; font-size: 13px; margin-bottom: 16px; }
+  .qr { margin: 16px 0; }
+  .btn { display: inline-block; background: #007aff; color: white; padding: 10px 24px; border-radius: 8px;
+         text-decoration: none; font-weight: 600; margin: 6px; font-size: 14px; }
+  .steps { text-align: left; font-size: 12px; color: #888; margin-top: 20px; line-height: 1.8; }
+</style></head><body>
+<div class="card">
+  <h1>Preflight Network Mock</h1>
+  <p class="sub">Proxy ${proxyHost}:${proxyPort}</p>
+  <div class="qr"><img src="qr.png" width="200" alt="QR Code"></div>
+  <a class="btn" href="preflight-ca.pem">CA 证书 (PEM)</a>
+  <a class="btn" href="preflight.mobileconfig">.mobileconfig</a>
+  <div class="steps">
+    <b>iOS:</b> 扫描二维码 或下载 .mobileconfig → 安装 →<br>
+    Settings > General > About > Certificate Trust Settings<br>
+    → 开启 <b>Preflight Mock CA</b><br>
+    <b>Android:</b> 下载 PEM → Settings > Security →<br>
+    Install certificate > CA certificate
+  </div>
+</div>
+</body></html>`;
+    }
+    isRunning() {
+        return this.server.getPort() > 0;
+    }
+    getStats() {
+        return this.server.getStats();
+    }
+    updateRules(rules) {
+        this.server.updateRules(rules);
+    }
+    getRootCACert() {
+        return this.server.getRootCACert();
+    }
+    generateMobileConfig(proxyHost, proxyPort) {
+        return this.server.generateMobileConfig(proxyHost, proxyPort);
+    }
+    setRecording(enabled) { this.server.setRecording(enabled); }
+    isRecording() { return this.server.isRecording(); }
+    getRecordedCount() { return this.server.getRecordedCount(); }
+    exportRecordedRules() {
+        const rules = this.server.exportRecordedRules();
+        this.server.clearRecording();
+        return rules;
+    }
+}

package/dist/mcp/network-mocks/device-proxy.js

@@ -0,0 +1,31 @@
+import { execSync } from "node:child_process";
+export function configureAndroidEmulatorProxy(config) {
+    const { deviceId, proxyHost, proxyPort } = config;
+    const proxy = `${proxyHost}:${proxyPort}`;
+    execSync(`adb -s ${deviceId} shell settings put global http_proxy ${proxy}`, {
+        stdio: "pipe",
+        timeout: 10_000,
+    });
+}
+export function removeAndroidEmulatorProxy(serial) {
+    execSync(`adb -s ${serial} shell settings put global http_proxy :0`, {
+        stdio: "pipe",
+        timeout: 10_000,
+    });
+}
+export function configureDeviceProxy(config) {
+    if (config.platform === "android") {
+        configureAndroidEmulatorProxy(config);
+    }
+    // iOS simulator proxy deferred to phase 2
+}
+export function removeDeviceProxy(platform, deviceId) {
+    if (platform === "android") {
+        removeAndroidEmulatorProxy(deviceId);
+    }
+    // iOS simulator proxy deferred to phase 2
+}
+/** Android emulator reaches the host at 10.0.2.2; iOS simulator uses loopback. */
+export function proxyHostForPlatform(platform) {
+    return platform === "android" ? "10.0.2.2" : "127.0.0.1";
+}

package/dist/mcp/network-mocks/index.js

@@ -0,0 +1,3 @@
+export { NetworkMockServer } from "./NetworkMockServer.js";
+export { NetworkMockService } from "./NetworkMockService.js";
+export { configureDeviceProxy, removeDeviceProxy, proxyHostForPlatform } from "./device-proxy.js";

package/dist/mcp/network-mocks/types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/runManager.js

@@ -134,7 +134,10 @@ export class RunManager {
     async refreshRun(runId) {
         const run = this.mustGet(runId);
         const [task, events, artifacts] = await Promise.all([
-            this.client.getTask(run.taskId),
+            this.client.getTask(run.taskId).catch((error) => {
+                logRun(runId, "REFRESH_ERROR", `getTask: ${error instanceof Error ? error.message : String(error)}`);
+                return run.task;
+            }),
             this.client.listEvents(run.taskId).catch(() => run.events),
             this.client.listArtifacts(run.taskId).catch(() => run.artifacts),
         ]);

package/dist/mcp/runtimeInstall.js

@@ -1,28 +1,62 @@
 import { spawn } from "node:child_process";
-import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+import { access, cp, mkdir, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { basename, dirname, join, sep } from "node:path";
 export async function installLocalRuntime(options) {
     const runtimeRoot = options.runtimeRoot ?? join(homedir(), ".preflight", "runtime");
-    await runNpm(["run", "build"], options.projectRoot);
+    const sourceRoot = options.sourceRoot ?? options.projectRoot;
+    const targetProjectRoot = options.targetProjectRoot ?? options.projectRoot ?? process.cwd();
+    const npmRunner = options.runNpm ?? runNpm;
+    if (!sourceRoot) {
+        throw new Error("Preflight runtime source root is required.");
+    }
+    if (await exists(join(sourceRoot, "tsconfig.build.json"))) {
+        await npmRunner(["run", "build"], sourceRoot);
+    }
     await rm(runtimeRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 500 });
     await mkdir(runtimeRoot, { recursive: true });
     await mkdir(join(runtimeRoot, "node", "bin"), { recursive: true });
     await cp(process.execPath, join(runtimeRoot, "node", "bin", "node"));
-    await cp(join(options.projectRoot, "dist"), join(runtimeRoot, "dist"), { recursive: true });
-    await cp(join(options.projectRoot, "package.json"), join(runtimeRoot, "package.json"));
-    await cp(join(options.projectRoot, "package-lock.json"), join(runtimeRoot, "package-lock.json"));
-    await cp(join(options.projectRoot, "scripts"), join(runtimeRoot, "scripts"), { recursive: true }).catch(() => { });
+    await cp(join(sourceRoot, "dist"), join(runtimeRoot, "dist"), { recursive: true });
+    await cp(join(sourceRoot, "package.json"), join(runtimeRoot, "package.json"));
+    await cp(join(sourceRoot, "package-lock.json"), join(runtimeRoot, "package-lock.json")).catch(() => { });
+    await cp(join(sourceRoot, "scripts"), join(runtimeRoot, "scripts"), { recursive: true }).catch(() => { });
     await mkdir(join(runtimeRoot, "docs"), { recursive: true });
-    await cp(join(options.projectRoot, "docs", "visual-flow-ir-llm.md"), join(runtimeRoot, "docs", "visual-flow-ir-llm.md"));
-    await runNpm(["ci", "--omit=dev"], runtimeRoot);
-    await writeFile(join(runtimeRoot, "preflight-runtime.json"), `${JSON.stringify({ installedAt: new Date().toISOString(), source: options.projectRoot }, null, 2)}\n`, "utf8");
+    await cp(join(sourceRoot, "docs", "visual-flow-ir-llm.md"), join(runtimeRoot, "docs", "visual-flow-ir-llm.md"));
+    const reusedDependencies = await reuseInstalledDependencies(sourceRoot, runtimeRoot);
+    if (!reusedDependencies) {
+        await npmRunner(await exists(join(runtimeRoot, "package-lock.json")) ? ["ci", "--omit=dev"] : ["install", "--omit=dev"], runtimeRoot);
+    }
+    await writeFile(join(runtimeRoot, "preflight-runtime.json"), `${JSON.stringify({ installedAt: new Date().toISOString(), source: sourceRoot, targetProjectRoot }, null, 2)}\n`, "utf8");
     return {
         runtimeRoot,
         nodeBin: join(runtimeRoot, "node", "bin", "node"),
         mcpEntry: join(runtimeRoot, "dist", "mcp", "cli.js"),
     };
 }
+async function reuseInstalledDependencies(sourceRoot, runtimeRoot) {
+    const packageNodeModules = join(sourceRoot, "node_modules");
+    if (await exists(packageNodeModules)) {
+        await cp(packageNodeModules, join(runtimeRoot, "node_modules"), { recursive: true });
+        return true;
+    }
+    const parentNodeModules = dirname(sourceRoot);
+    const isNpxPackage = basename(parentNodeModules) === "node_modules" && parentNodeModules.includes(`${sep}_npx${sep}`);
+    if (isNpxPackage) {
+        await cp(parentNodeModules, join(runtimeRoot, "node_modules"), { recursive: true });
+        return true;
+    }
+    return false;
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function run(command, args, cwd) {
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, { cwd, stdio: "inherit" });

package/dist/mcp/server.js

@@ -13,8 +13,12 @@ import { loadPreflightUserConfig } from "./userConfig.js";
 import { compileVisualFlow, validateVisualFlow } from "./visual-flow/index.js";
 import { registerExplorationTools } from "./exploration/index.js";
 import { createMidsceneSessionFromResourceId, ensureIosWdaStarted } from "./exploration/tools-session.js";
+import { NetworkMockService } from "./network-mocks/NetworkMockService.js";
+import { proxyHostForPlatform } from "./network-mocks/device-proxy.js";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
+const MCP_SAFE_WAIT_MS = 45_000;
+const RUN_POLL_INTERVAL_MS = 2_000;
 export function createPreflightMcpServer(options = {}) {
     const agentBaseUrl = options.agentBaseUrl ?? process.env.AGENT_BASE_URL ?? "http://127.0.0.1:18998";
     const livePort = options.livePort ?? Number(process.env.MCP_LIVE_PORT ?? "18999");
@@ -25,6 +29,7 @@ export function createPreflightMcpServer(options = {}) {
     const runtime = new AgentRuntimeManager({ projectRoot, agentBaseUrl, client, env: process.env, runtimeRoot: options.runtimeRoot, loadConfigEnv });
     const liveBaseUrl = `http://127.0.0.1:${livePort}`;
     const runManager = new RunManager(client, liveBaseUrl);
+    const networkMockService = new NetworkMockService();
     let liveServerStarted;
     const server = new McpServer({ name: "Preflight", version: "0.1.0" });
     server.registerTool("agent_health", {
@@ -119,18 +124,38 @@ export function createPreflightMcpServer(options = {}) {
             waitForCompletion: z.boolean().optional().describe("Set to false for multi-step flows (3+ steps) — returns immediately with a runId, then poll with watch_run. " +
                 "Set to true only for very short flows (1-2 steps) that finish within the MCP 60s transport timeout."),
             timeoutMs: z.number().int().positive().optional().describe("Maximum wait time in milliseconds for the test to complete. " +
-                "Calculate as: number of visual flow steps × 60000 (1 minute per step). " +
-                "For example, a 5-step flow should set timeoutMs to 300000. " +
-                "Default is 120000 (2 minutes) which is only suitable for very short flows (1-2 steps). " +
+                "Capped internally at 45000ms so the MCP response returns before the 60s transport timeout. " +
                 "NOTE: Only effective when waitForCompletion is true. " +
-                "MCP transport has a 60s hard timeout — if timeoutMs exceeds 60s, " +
-                "use waitForCompletion: false and poll with watch_run instead."),
+                "For long runs, use waitForCompletion: false and poll with watch_run instead."),
         },
     }, async (input) => {
         await runtime.ensureStarted();
         const parsed = validateVisualFlow(input.visualFlow);
         if (!parsed.ok)
             return jsonResult(parsed);
+        const hasNetworkMocks = (parsed.value.networkMocks?.length ?? 0) > 0;
+        let mocksStarted = false;
+        if (hasNetworkMocks && input.resourceId) {
+            const deviceId = input.resourceId.includes(":") ? input.resourceId.split(":")[1] : input.resourceId;
+            const platform = input.platform.toLowerCase();
+            try {
+                await networkMockService.start({
+                    rules: parsed.value.networkMocks,
+                    platform,
+                    deviceId,
+                });
+                mocksStarted = true;
+            }
+            catch (err) {
+                return jsonResult({
+                    ok: false,
+                    message: `启动网络 mock 失败: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        }
+        else if (hasNetworkMocks && !input.resourceId) {
+            // Mocks defined but no device — note for manual setup
+        }
         liveServerStarted ??= startLiveViewer(livePort, runManager).then((viewer) => {
             runManager.setLiveBaseUrl(viewer.baseUrl);
         });
@@ -146,38 +171,51 @@ export function createPreflightMcpServer(options = {}) {
             runtimeEnv: { ...preflightRunDefaults(), ...(await loadConfigEnv()), ...input.runtimeEnv },
             visualFlow: parsed.value,
         });
-        if (!input.waitForCompletion)
-            return jsonResult({ ...started, visualFlow: parsed.value });
-        return jsonResult(await runManager.waitForRun(started.runId, input.timeoutMs ?? 120_000, 2_000));
+        if (!input.waitForCompletion) {
+            return jsonResult({
+                ...started,
+                visualFlow: parsed.value,
+                ...(mocksStarted ? { networkMocksActive: true } : {}),
+            });
+        }
+        const result = await runManager.waitForRun(started.runId, safeMcpWaitMs(input.timeoutMs), RUN_POLL_INTERVAL_MS);
+        if (mocksStarted) {
+            try {
+                await networkMockService.stop();
+            }
+            catch { /* cleanup */ }
+        }
+        return jsonResult(result);
     });
     server.registerTool("watch_run", {
         title: "Watch Test Run",
         description: "Refresh and summarize a test run. Use while the live viewer is open. " +
             "For long-running tests that exceed the MCP transport timeout (60s): " +
             "(1) Call run_flow with waitForCompletion: false to get a runId. " +
-            "(2) Call watch_run with minIntervalMs (e.g. 30000 = check every 30s) to poll. " +
-            "minIntervalMs blocks on the server side and polls the agent every 2s internally, " +
-            "so one call covers one full interval without consuming tokens on intermediate checks. " +
+            "(2) Call watch_run to poll the run. It waits up to 45s by default and returns early when the run succeeds or fails. " +
             "Do NOT call run_flow again — that creates a duplicate run.",
         inputSchema: {
             runId: z.string(),
             waitForCompletion: z.boolean().optional().describe("Set to true to block until the run finishes (respects timeoutMs). " +
                 "Omit or set to false for a lightweight status check — use this for polling."),
             timeoutMs: z.number().int().positive().optional().describe("Maximum wait time in milliseconds. " +
-                "Based on the total number of steps in the original visual flow: steps × 60000. " +
-                "Default is 120000 (2 minutes). " +
+                "Capped internally at 45000ms so the MCP response returns before the 60s transport timeout. " +
                 "NOTE: Only effective when waitForCompletion is true. " +
-                "Due to MCP 60s transport timeout, prefer polling without waitForCompletion for long runs."),
-            minIntervalMs: z.number().int().positive().optional().describe("Block for at least this many milliseconds before returning. " +
-                "While blocked, the server polls the agent every 2s internally. " +
-                "If the run finishes early, returns immediately. " +
-                "Use 30000 for a ~30s polling cadence without consuming extra tokens " +
-                "on intermediate calls. Capped internally to 55000 to leave headroom " +
-                "for the 60s MCP transport timeout."),
+                "Prefer polling without waitForCompletion for long runs."),
         },
-    }, async ({ runId, waitForCompletion, timeoutMs, minIntervalMs }) => {
+    }, async ({ runId, waitForCompletion, timeoutMs }) => {
         await runtime.ensureStarted();
-        return jsonResult(waitForCompletion ? await runManager.waitForRun(runId, timeoutMs ?? 120_000, 2_000) : await runManager.watchRun(runId, minIntervalMs));
+        const summary = waitForCompletion
+            ? await runManager.waitForRun(runId, safeMcpWaitMs(timeoutMs), RUN_POLL_INTERVAL_MS)
+            : await runManager.watchRun(runId, MCP_SAFE_WAIT_MS);
+        // Auto-cleanup mocks on terminal state
+        if (["SUCCESS", "FAILED", "CANCELLED"].includes(summary.status) && networkMockService.isRunning()) {
+            try {
+                await networkMockService.stop();
+            }
+            catch { /* cleanup */ }
+        }
+        return jsonResult(summary);
     });
     server.registerTool("cancel_run", {
         title: "Cancel Test Run",
@@ -189,7 +227,15 @@ export function createPreflightMcpServer(options = {}) {
         },
     }, async ({ runId, reason }) => {
         await runtime.ensureStarted();
-        return jsonResult(await runManager.cancelRun(runId, "model", reason ?? "no reason given"));
+        const result = await runManager.cancelRun(runId, "model", reason ?? "no reason given");
+        // Clean up network mocks if they were auto-started for this run
+        if (networkMockService.isRunning()) {
+            try {
+                await networkMockService.stop();
+            }
+            catch { /* cleanup */ }
+        }
+        return jsonResult(result);
     });
     server.registerTool("save_report", {
         title: "Save Test Report",
@@ -226,6 +272,162 @@ export function createPreflightMcpServer(options = {}) {
         const result = await readReport(reportDir);
         return jsonResult(result);
     });
+    server.registerTool("start_network_mocks", {
+        title: "Start Network Mocks",
+        description: "Start the network mock HTTP/HTTPS proxy server and configure the device to route traffic through it. " +
+            "Matching requests return mock responses; non-matching traffic is forwarded transparently. " +
+            "Automatically generates a Root CA certificate for HTTPS MITM interception. " +
+            "Use before a test run to mock API responses that the app depends on. " +
+            "Currently supports Android emulator (iOS simulator deferred to phase 2).",
+        inputSchema: {
+            platform: z.enum(["ANDROID", "IOS"]).describe("Device platform"),
+            resourceId: z.string().describe("Device resource ID from list_devices (e.g., android:emulator-5554)"),
+            port: z.number().int().positive().optional().describe("Preferred port (e.g., to match existing device proxy config)"),
+            rules: z.array(z.object({
+                urlPattern: z.string().describe("Substring to match against the full request URL"),
+                method: z.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).optional().describe("HTTP method to match (default: any)"),
+                responses: z.array(z.object({
+                    status: z.number().int().min(100).max(599).optional().describe("HTTP status code (default: 200)"),
+                    body: z.string().describe("Response body, typically a JSON string"),
+                    requestBodyMatch: z.record(z.string()).optional().describe("Key-value pairs that must match in the request body"),
+                    callIndex: z.number().int().positive().optional().describe("Only match on the nth call (1-based, for stateful sequences)"),
+                    headers: z.record(z.string()).optional().describe("Optional response headers"),
+                    delay: z.number().int().min(0).optional().describe("Delay in ms before responding"),
+                })),
+                description: z.string().optional().describe("Human-readable description"),
+            })),
+        },
+    }, async (input) => {
+        await runtime.ensureStarted();
+        const platform = input.platform.toLowerCase();
+        const deviceId = input.resourceId.includes(":") ? input.resourceId.split(":")[1] : input.resourceId;
+        const rules = input.rules.map((r) => ({
+            urlPattern: r.urlPattern,
+            ...(r.method ? { method: r.method } : {}),
+            responses: r.responses.map((resp) => ({
+                ...(resp.status != null ? { status: resp.status } : {}),
+                body: resp.body,
+                ...(resp.requestBodyMatch ? { requestBodyMatch: resp.requestBodyMatch } : {}),
+                ...(resp.callIndex != null ? { callIndex: resp.callIndex } : {}),
+                ...(resp.headers ? { headers: resp.headers } : {}),
+                ...(resp.delay != null ? { delay: resp.delay } : {}),
+            })),
+            ...(r.description ? { description: r.description } : {}),
+        }));
+        return jsonResult(await networkMockService.start({ rules, platform, deviceId, preferredPort: input.port }));
+    });
+    server.registerTool("stop_network_mocks", {
+        title: "Stop Network Mocks",
+        description: "Stop the network mock server and remove device proxy configuration. " +
+            "Call this after the test completes to restore normal network traffic.",
+    }, async () => jsonResult(await networkMockService.stop()));
+    server.registerTool("get_network_mock_status", {
+        title: "Get Network Mock Status",
+        description: "Get the current network mock server status and per-rule call statistics. " +
+            "Use to verify that mocks are being hit as expected during a test.",
+    }, async () => jsonResult(networkMockService.getStats()));
+    server.registerTool("update_network_mock_rules", {
+        title: "Update Network Mock Rules",
+        description: "Hot-reload mock rules without stopping the server. " +
+            "Use to change mock responses mid-test without restarting the proxy.",
+        inputSchema: {
+            rules: z.array(z.object({
+                urlPattern: z.string(),
+                method: z.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).optional(),
+                responses: z.array(z.object({
+                    status: z.number().int().min(100).max(599).optional(),
+                    body: z.string(),
+                    requestBodyMatch: z.record(z.string()).optional(),
+                    callIndex: z.number().int().positive().optional(),
+                    headers: z.record(z.string()).optional(),
+                    delay: z.number().int().min(0).optional(),
+                })),
+                description: z.string().optional(),
+            })),
+        },
+    }, async ({ rules }) => {
+        const parsed = rules.map((r) => ({
+            urlPattern: r.urlPattern,
+            ...(r.method ? { method: r.method } : {}),
+            responses: r.responses.map((resp) => ({
+                ...(resp.status != null ? { status: resp.status } : {}),
+                body: resp.body,
+                ...(resp.requestBodyMatch ? { requestBodyMatch: resp.requestBodyMatch } : {}),
+                ...(resp.callIndex != null ? { callIndex: resp.callIndex } : {}),
+                ...(resp.headers ? { headers: resp.headers } : {}),
+                ...(resp.delay != null ? { delay: resp.delay } : {}),
+            })),
+            ...(r.description ? { description: r.description } : {}),
+        }));
+        networkMockService.updateRules(parsed);
+        return jsonResult({ ok: true, updated: parsed.length });
+    });
+    server.registerTool("get_root_ca_cert", {
+        title: "Get Root CA Certificate",
+        description: "Export the Preflight MITM Root CA certificate (PEM format). " +
+            "Install this certificate on your iOS/Android device to enable HTTPS interception. " +
+            "iOS: Send the cert to the device (e.g. AirDrop), open it, go to Settings > Profile Downloaded > Install. " +
+            "Then Settings > General > About > Certificate Trust Settings > Enable full trust for 'Preflight Mock CA'. " +
+            "Android: Settings > Security > Encryption & credentials > Install a certificate > CA certificate. " +
+            "Only available when network mocks are running.",
+    }, async () => {
+        const cert = networkMockService.getRootCACert();
+        if (!cert)
+            return jsonResult({ ok: false, message: "network mocks not running — call start_network_mocks first" });
+        return { content: [{ type: "text", text: cert }] };
+    });
+    server.registerTool("get_mobile_config", {
+        title: "Get iOS Mobile Config",
+        description: "Generate an iOS .mobileconfig profile that installs the CA certificate AND configures the WiFi proxy " +
+            "in one step. Send this file to the iOS device (e.g. AirDrop), open it to install. " +
+            "After installation, go to Settings > General > About > Certificate Trust Settings > enable 'Preflight Mock CA'. " +
+            "The proxy host will be auto-detected as this machine's local IP. " +
+            "Only available when network mocks are running.",
+    }, async () => {
+        if (!networkMockService.isRunning()) {
+            return jsonResult({ ok: false, message: "network mocks not running — call start_network_mocks first" });
+        }
+        const port = networkMockService.getStats().port;
+        if (!port)
+            return jsonResult({ ok: false, message: "mock server port unknown" });
+        const proxyHost = proxyHostForPlatform("ios") === "127.0.0.1" ? "172.23.166.53" : proxyHostForPlatform("ios");
+        const config = networkMockService.generateMobileConfig(proxyHost, port);
+        if (!config)
+            return jsonResult({ ok: false, message: "failed to generate mobileconfig" });
+        return { content: [{ type: "text", text: config }] };
+    });
+    server.registerTool("start_recording", {
+        title: "Start Network Recording",
+        description: "Start recording network traffic through the mock proxy. All requests and responses are captured " +
+            "and can be exported as mock rules via export_recorded_rules. Network mocks must already be running.",
+    }, async () => {
+        if (!networkMockService.isRunning()) {
+            return jsonResult({ ok: false, message: "network mocks not running — call start_network_mocks first" });
+        }
+        networkMockService.setRecording(true);
+        return jsonResult({ ok: true, message: "Recording started" });
+    });
+    server.registerTool("stop_recording", {
+        title: "Stop Network Recording",
+        description: "Stop recording and return the count of captured requests.",
+    }, async () => {
+        if (!networkMockService.isRunning()) {
+            return jsonResult({ ok: false, message: "network mocks not running" });
+        }
+        const count = networkMockService.getRecordedCount();
+        networkMockService.setRecording(false);
+        return jsonResult({ ok: true, recorded: count });
+    });
+    server.registerTool("export_recorded_rules", {
+        title: "Export Recorded Rules",
+        description: "Export recorded network traffic as NetworkMockRule[]. " +
+            "Duplicated URLs are merged, request bodies generate requestBodyMatch rules, " +
+            "and sequential responses are assigned callIndex. " +
+            "Use after stop_recording to convert captured traffic into reusable mock rules.",
+    }, async () => {
+        const rules = networkMockService.exportRecordedRules();
+        return jsonResult({ ok: true, count: rules.length, rules });
+    });
     registerExplorationTools(server, { client, loadConfigEnv, ensureAgentStarted: async () => { await runtime.ensureStarted(); }, createSessionFromMeta: createMidsceneSessionFromResourceId, projectRoot });
     return server;
 }
@@ -234,6 +436,9 @@ function jsonResult(value) {
         content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
     };
 }
+function safeMcpWaitMs(timeoutMs) {
+    return Math.min(timeoutMs ?? MCP_SAFE_WAIT_MS, MCP_SAFE_WAIT_MS);
+}
 function preflightRunDefaults() {
     return {
         MIDSCENE_OUTPUT_FORMAT: "html-and-external-assets",
@@ -243,6 +448,7 @@ function preflightRunDefaults() {
         MIDSCENE_RECORD_VIDEO_CRF: "32",
         MIDSCENE_RECORD_VIDEO_PRESET: "fast",
         MIDSCENE_RUN_TIMEOUT_MS: "1200000", // 20分钟，适配多步骤流程
+        MIDSCENE_REPLANNING_CYCLE_LIMIT: "10", // 避免死循环
     };
 }
 const VISUAL_FLOW_LLM_HARD_RULES = `# Preflight Visual Flow IR hard rules

package/dist/mcp/setup.js

@@ -7,7 +7,11 @@ export async function setupLocalMcp(options) {
     const livePort = options.livePort ?? 18999;
     const shouldInstallRuntime = options.installRuntime ?? true;
     const installedRuntime = shouldInstallRuntime
-        ? await installLocalRuntime({ projectRoot: options.projectRoot, runtimeRoot: options.runtimeRoot })
+        ? await installLocalRuntime({
+            sourceRoot: options.runtimeSourceRoot ?? options.projectRoot,
+            targetProjectRoot: options.projectRoot,
+            runtimeRoot: options.runtimeRoot,
+        })
         : undefined;
     const runtimeRoot = installedRuntime?.runtimeRoot ?? options.runtimeRoot ?? process.env.AGENT_RUNTIME_ROOT?.trim();
     const isRuntime = !!runtimeRoot;
@@ -125,8 +129,8 @@ alwaysApply: false
 7. 调用 \`validate_visual_flow\`。如果校验失败，按 message 修正 visualFlow 后再次校验。
 8. 生成最小测试用例：先覆盖改动点，再补必要回归。
 9. 如用户给了 app 包，先调用 \`install_app\`。
-10. 调用 \`run_flow\`，把返回的 liveUrl 明确给用户，让用户可以打开浏览器看实时执行。
-11. 执行中调用 \`watch_run\` 观察状态。失败时先判断是环境/设备、IR 用例步骤、agent runtime 还是真实业务问题。
+10. 调用 \`run_flow\` 时必须设置 \`waitForCompletion: false\`，让工具立即返回 runId/liveUrl；不要用 \`waitForCompletion: true\` 等待完整流程，避免 MCP 60 秒传输超时。
+11. 执行中调用 \`watch_run\` 观察状态；工具默认等待最多 45 秒，run 一旦成功或失败会提前返回。失败时先判断是环境/设备、IR 用例步骤、agent runtime 还是真实业务问题。
 12. 如果失败原因是 IR 步骤不合理，只能调整 visualFlow 后重跑；不要读取或手写 Midscene TS 脚本。若是 Preflight 编译器/runtime 内部错误，停止并报告为工具缺陷。
 13. 最终调用 \`save_report\`，并在回复中给出测试报告、report/liveUrl 和 PASS/FAIL 结论。
 `;
@@ -161,8 +165,8 @@ Workflow:
 6. Read \`get_visual_flow_ir_rules\` and generate visualFlow JSON, not raw Midscene TypeScript.
 7. Validate with \`validate_visual_flow\`; fix the JSON until validation passes.
 8. Install the app when an app package path is provided.
-9. Start the run with \`run_flow\` and show the returned liveUrl.
-10. Poll with \`watch_run\`.
+9. Start the run with \`run_flow\` using \`waitForCompletion: false\`, then show the returned liveUrl. Never wait for a full flow inside \`run_flow\`; MCP transport can time out after about 60 seconds.
+10. Poll with \`watch_run\`; it waits up to 45s by default and returns early when the run succeeds or fails.
 11. Analyze failures before retrying. Distinguish device/env failures, brittle IR steps, agent runtime failures, and real app bugs. For IR problems, revise visualFlow only; never switch to raw Midscene script repair.
 12. Save report with \`save_report\`.