preflite 1.0.1

package/dist/mcp/agentRuntime.js

@@ -0,0 +1,184 @@
+import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export class AgentRuntimeManager {
+    options;
+    child;
+    logStream;
+    startPromise;
+    logPath;
+    pidPath;
+    runtimeRoot;
+    preflightHome;
+    constructor(options) {
+        this.options = options;
+        this.runtimeRoot = options.runtimeRoot ?? (process.env.AGENT_RUNTIME_ROOT?.trim() || undefined);
+        this.preflightHome = process.env.PREFLIGHT_HOME?.trim() || join(homedir(), ".preflight");
+        this.logPath = join(this.preflightHome, "runtime", "agent.log");
+        this.pidPath = join(this.preflightHome, "runtime", "agent.pid");
+    }
+    /** 运行模式 */
+    get mode() {
+        return this.runtimeRoot ? "runtime" : "dev";
+    }
+    async status() {
+        const health = await this.options.client.health();
+        if (health.ok) {
+            return {
+                ok: true,
+                state: "running",
+                message: "automation-agent HTTP is reachable.",
+                pid: this.child?.pid ?? (await this.readPid()),
+                health,
+                logPath: this.logPath,
+                pidPath: this.pidPath,
+                baseUrl: this.options.agentBaseUrl,
+            };
+        }
+        return {
+            ok: false,
+            state: "stopped",
+            message: `automation-agent HTTP is not reachable: ${health.error ?? "unknown error"}`,
+            pid: this.child?.pid ?? (await this.readPid()),
+            health,
+            logPath: this.logPath,
+            pidPath: this.pidPath,
+            baseUrl: this.options.agentBaseUrl,
+        };
+    }
+    async ensureStarted() {
+        const current = await this.status();
+        if (current.ok)
+            return current;
+        if (this.startPromise)
+            return this.startPromise;
+        this.startPromise = this.start();
+        try {
+            return await this.startPromise;
+        }
+        finally {
+            this.startPromise = undefined;
+        }
+    }
+    async stop() {
+        if (!this.child || this.child.killed) {
+            return this.status();
+        }
+        const pid = this.child.pid;
+        this.child.kill("SIGTERM");
+        await delay(500);
+        const health = await this.options.client.health();
+        return {
+            ok: !health.ok,
+            state: health.ok ? "running" : "stopped",
+            message: health.ok ? "automation-agent is still reachable after SIGTERM." : "automation-agent stopped.",
+            pid,
+            health,
+            logPath: this.logPath,
+            pidPath: this.pidPath,
+            baseUrl: this.options.agentBaseUrl,
+        };
+    }
+    async start() {
+        await mkdir(dirname(this.logPath), { recursive: true });
+        this.logStream = createWriteStream(this.logPath, { flags: "a" });
+        this.logStream.write(`\n[preflight-mcp] starting automation-agent (${this.mode} mode) at ${new Date().toISOString()}\n`);
+        const port = portFromBaseUrl(this.options.agentBaseUrl) ?? 18998;
+        const configEnv = (await this.options.loadConfigEnv?.()) ?? {};
+        const env = {
+            ...(this.options.env ?? process.env),
+            ...configEnv,
+            LOCAL_MCP_MODE: "1",
+            PREFLIGHT_HOME: this.preflightHome,
+            AGENT_HOME: this.preflightHome,
+            AGENT_HTTP_PORT: String(port),
+            AGENT_HTTP_TOKEN: "",
+            PLATFORM_WS_TOKEN: "",
+            PLATFORM_AGENT_CALLBACK_TOKEN: "",
+            PLATFORM_CALLBACK_ENDPOINT: "",
+            PLATFORM_COMMAND_POLL_BASE_URL: "",
+            MCP_AGENT_AUTOSTART: "1",
+        };
+        if (this.runtimeRoot) {
+            // Runtime 模式：使用打包后的 node + dist
+            const nodeBin = join(this.runtimeRoot, "node", "bin", "node");
+            const entry = join(this.runtimeRoot, "dist", "main.js");
+            this.logStream.write(`[preflight-mcp] runtimeRoot=${this.runtimeRoot} node=${nodeBin} entry=${entry}\n`);
+            this.child = spawn(nodeBin, [entry], {
+                cwd: this.runtimeRoot,
+                env,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        else {
+            // 开发模式：使用 npm exec tsx
+            this.child = spawn("npm", ["--silent", "--prefix", this.options.projectRoot, "exec", "tsx", "src/main.ts"], {
+                cwd: this.options.projectRoot,
+                env,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        this.child.stdout?.pipe(this.logStream, { end: false });
+        this.child.stderr?.pipe(this.logStream, { end: false });
+        this.child.on("exit", (code, signal) => {
+            this.logStream?.write(`[preflight-mcp] automation-agent exited code=${code ?? ""} signal=${signal ?? ""}\n`);
+        });
+        if (this.child.pid) {
+            await writeFile(this.pidPath, `${this.child.pid}\n`, "utf8");
+        }
+        const deadline = Date.now() + 30_000;
+        while (Date.now() < deadline) {
+            const health = await this.options.client.health();
+            if (health.ok) {
+                return {
+                    ok: true,
+                    state: "started",
+                    message: "automation-agent started and HTTP is reachable.",
+                    pid: this.child.pid,
+                    health,
+                    logPath: this.logPath,
+                    pidPath: this.pidPath,
+                    baseUrl: this.options.agentBaseUrl,
+                };
+            }
+            if (this.child.exitCode !== null)
+                break;
+            await delay(500);
+        }
+        const health = await this.options.client.health();
+        return {
+            ok: false,
+            state: "failed",
+            message: `automation-agent did not become ready in ${this.mode} mode. Check logPath: ${this.logPath}`,
+            pid: this.child.pid,
+            health,
+            logPath: this.logPath,
+            pidPath: this.pidPath,
+            baseUrl: this.options.agentBaseUrl,
+        };
+    }
+    async readPid() {
+        try {
+            const text = await readFile(this.pidPath, "utf8");
+            const pid = Number(text.trim());
+            return Number.isFinite(pid) && pid > 0 ? Math.floor(pid) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+function portFromBaseUrl(baseUrl) {
+    try {
+        const port = Number(new URL(baseUrl).port);
+        return Number.isFinite(port) && port > 0 ? Math.floor(port) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/mcp/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createPreflightMcpServer } from "./server.js";
+import { setupLocalMcp } from "./setup.js";
+// Prevent unhandled rejections / exceptions from crashing the server mid-session
+process.on("unhandledRejection", (reason) => {
+    console.error("[Preflight-MCP] unhandledRejection:", reason);
+});
+process.on("uncaughtException", (err) => {
+    console.error("[Preflight-MCP] uncaughtException:", err);
+});
+const command = process.argv[2] ?? "serve";
+if (command === "serve") {
+    const runtimeRoot = argValue("--runtime-root") ?? (process.env.AGENT_RUNTIME_ROOT?.trim() || undefined);
+    const server = createPreflightMcpServer({ runtimeRoot });
+    await server.connect(new StdioServerTransport());
+}
+else if (command === "setup") {
+    const projectRoot = argValue("--project-root") ?? process.cwd();
+    const agentBaseUrl = argValue("--agent-base-url") ?? process.env.AGENT_BASE_URL ?? "http://127.0.0.1:18998";
+    const livePort = Number(argValue("--live-port") ?? process.env.MCP_LIVE_PORT ?? "18999");
+    const runtimeRoot = argValue("--runtime-root") ?? process.env.AGENT_RUNTIME_ROOT?.trim() ?? undefined;
+    const installRuntime = !process.argv.includes("--no-install-runtime");
+    const result = await setupLocalMcp({ projectRoot, agentBaseUrl, livePort, runtimeRoot, installRuntime });
+    console.log(JSON.stringify({ ok: true, ...result }, null, 2));
+}
+else {
+    console.error(`Unknown Preflight MCP command: ${command}`);
+    process.exitCode = 2;
+}
+function argValue(name) {
+    const idx = process.argv.indexOf(name);
+    if (idx < 0)
+        return undefined;
+    return process.argv[idx + 1];
+}

package/dist/mcp/doctor.js

@@ -0,0 +1,124 @@
+import { spawn } from "node:child_process";
+import http from "node:http";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const MIDSCENE_KEY_NAMES = [
+    "MIDSCENE_MODEL_API_KEY",
+    "MIDSCENE_API_KEY",
+    "MIDSCENE_OPENAI_API_KEY",
+    "OPENAI_API_KEY",
+    "ANTHROPIC_API_KEY",
+];
+// ---------------------------------------------------------------------------
+// iOS WebDriverAgent health check
+// ---------------------------------------------------------------------------
+function checkWdaHealth(host, port, timeoutMs) {
+    return new Promise((resolve) => {
+        const req = http.get(`http://${host}:${port}/status`, { timeout: timeoutMs }, (res) => {
+            let body = "";
+            res.on("data", (chunk) => {
+                body += chunk;
+            });
+            res.on("end", () => resolve(body.trim().length > 0));
+        });
+        req.on("error", () => resolve(false));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve(false);
+        });
+    });
+}
+async function iosWdaHealthCheck(env) {
+    const host = env.MIDSCENE_IOS_WDA_HOST || "127.0.0.1";
+    const defaultPort = Number(env.MIDSCENE_IOS_WDA_PORT) || 8200;
+    const candidates = new Set();
+    // Try to discover running WDA ports from the watchdog port map
+    const portMapPath = env.IOS_WDA_PORT_MAP_FILE_PATH
+        || join(homedir(), ".preflight", "runtime", ".wda-agent-state", "wda-port-map.json");
+    try {
+        const raw = await readFile(portMapPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.portsByUdid) {
+            for (const p of Object.values(parsed.portsByUdid)) {
+                if (typeof p === "number" && Number.isFinite(p) && p > 0) {
+                    candidates.add(Math.floor(p));
+                }
+            }
+        }
+    }
+    catch {
+        // port map not found — fall back to default port
+    }
+    candidates.add(defaultPort);
+    for (const port of candidates) {
+        if (await checkWdaHealth(host, port, 2000)) {
+            return {
+                id: "ios-wda",
+                title: "iOS WebDriverAgent",
+                status: "pass",
+                message: `WebDriverAgent is healthy on ${host}:${port}.`,
+            };
+        }
+    }
+    const portList = [...candidates].sort((a, b) => a - b).join(", ");
+    return {
+        id: "ios-wda",
+        title: "iOS WebDriverAgent",
+        status: "warn",
+        message: `WebDriverAgent is not running (checked host=${host}, ports=${portList}). iOS automation needs WDA. Call "start_ios_wda" tool to start it, or ensure the WDA watchdog is running.`,
+    };
+}
+export async function runDoctor(deps) {
+    const commandExists = deps.commandExists ?? defaultCommandExists;
+    const checks = [];
+    const agent = await deps.agentHealth();
+    checks.push({
+        id: "agent-http",
+        title: "Automation Agent HTTP",
+        status: agent.ok ? "pass" : "fail",
+        message: agent.ok ? "Agent HTTP is reachable." : `Agent HTTP is not reachable: ${agent.error ?? "unknown error"}`,
+    });
+    const keyName = MIDSCENE_KEY_NAMES.find((name) => deps.env[name]?.trim());
+    checks.push({
+        id: "midscene-api-key",
+        title: "Midscene API Key",
+        status: keyName ? "pass" : "fail",
+        message: keyName
+            ? `${keyName} is set.`
+            : `Missing Midscene model API key. Set one of: ${MIDSCENE_KEY_NAMES.join(", ")}.`,
+    });
+    checks.push(await commandCheck("android-adb", "Android adb", "adb", commandExists, "Android tests need adb in PATH."));
+    checks.push(await commandCheck("ffmpeg", "ffmpeg", "ffmpeg", commandExists, "Video recording needs ffmpeg in PATH."));
+    checks.push(await commandCheck("scrcpy", "scrcpy", "scrcpy", commandExists, "Android video recording needs scrcpy in PATH."));
+    checks.push(await commandCheck("harmony-hdc", "Harmony hdc", deps.env.MIDSCENE_HARMONY_HDC_PATH || deps.env.AGENT_HARMONY_HDC_PATH || "hdc", commandExists, "Harmony tests need hdc or MIDSCENE_HARMONY_HDC_PATH."));
+    checks.push(await commandCheck("ios-xcode", "iOS Xcode tools", "xcrun", commandExists, "iOS tests need Xcode command line tools."));
+    checks.push(await commandCheck("ios-iproxy", "iOS iproxy", "iproxy", commandExists, "iOS WDA live view needs iproxy."));
+    checks.push(await iosWdaHealthCheck(deps.env));
+    const blocking = checks.filter((check) => check.status === "fail");
+    const nonPass = checks.filter((check) => check.status !== "pass");
+    return {
+        ok: blocking.length === 0,
+        summary: blocking.length === 0 ? "All blocking checks passed." : `${blocking.length} blocking issue(s) found.`,
+        checks: nonPass,
+    };
+}
+async function commandCheck(id, title, command, commandExists, missingMessage) {
+    const exists = await commandExists(command);
+    return {
+        id,
+        title,
+        status: exists ? "pass" : "warn",
+        message: exists ? `${command} is available.` : missingMessage,
+    };
+}
+function defaultCommandExists(command) {
+    return new Promise((resolve) => {
+        const child = spawn("sh", ["-lc", `command -v ${shellQuote(command)} >/dev/null 2>&1`], { stdio: "ignore" });
+        child.on("close", (code) => resolve(code === 0));
+        child.on("error", () => resolve(false));
+    });
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/dist/mcp/evidence.js

@@ -0,0 +1,57 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export async function writeEvidence(input) {
+    const runDir = join(input.outputRoot ?? join(homedir(), ".preflight"), "self-test-runs", input.run.runId);
+    await mkdir(runDir, { recursive: true });
+    const evidencePath = join(runDir, "evidence.md");
+    const metadataPath = join(runDir, "metadata.json");
+    await writeFile(evidencePath, renderEvidenceMarkdown(input.run), "utf8");
+    await writeFile(metadataPath, JSON.stringify(input.run, null, 2), "utf8");
+    return { runDir, evidencePath, metadataPath };
+}
+function renderEvidenceMarkdown(run) {
+    const artifactLines = run.artifacts.length
+        ? run.artifacts.map((artifact) => `- ${artifact.type}: ${artifact.uri}`).join("\n")
+        : "- 暂无产物";
+    return `# 自测留痕
+
+- 结果：${run.status}
+- 时间：${run.createdAt} -> ${run.updatedAt}
+- 平台：${run.platform ?? "unknown"}
+- 设备：${run.resourceId ?? "auto"}
+- App 包：${run.appRef ?? "未指定"}
+- Task ID：${run.taskId}
+- Run ID：${run.runId}
+- Live Viewer：${run.liveUrl}
+
+## 测试意图
+
+${run.testIntent ?? "未填写"}
+
+## 执行脚本
+
+\`\`\`ts
+${run.script ?? ""}
+\`\`\`
+
+## Visual Flow
+
+\`\`\`json
+${run.visualFlow ? JSON.stringify(run.visualFlow, null, 2) : "{}"}
+\`\`\`
+
+## 结果摘要
+
+${run.failureAnalysis.summary}
+
+## 失败原因
+
+- 分类：${run.failureAnalysis.category}
+- 建议：${run.failureAnalysis.recommendation}
+
+## 产物
+
+${artifactLines}
+`;
+}

package/dist/mcp/exploration/index.js

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import { getExplorationStartHandler, getExplorationEndHandler, } from "./tools-session.js";
+import { getPageSummaryHandler, askAboutScreenHandler, aiActHandler, } from "./tools-intelligent.js";
+import { getScreenshotHandler, getTypeHandler, getWaitHandler, } from "./tools-atomic.js";
+function jsonResult(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    };
+}
+/**
+ * Register all exploration MCP tools on the given server instance.
+ * Handlers are created once at the top and reused for each tool registration.
+ */
+export function registerExplorationTools(server, ctx) {
+    // Instantiate all handler functions once
+    const startHandler = getExplorationStartHandler(ctx);
+    const endHandler = getExplorationEndHandler();
+    const pageSummaryHandler = getPageSummaryHandler(ctx);
+    const askHandler = askAboutScreenHandler(ctx);
+    const actHandler = aiActHandler(ctx);
+    const screenshotHandler = getScreenshotHandler(ctx);
+    const typeHandler = getTypeHandler(ctx);
+    const waitHandler = getWaitHandler(ctx);
+    // ---------------------------------------------------------------------------
+    // 1. exploration_start
+    // ---------------------------------------------------------------------------
+    server.registerTool("exploration_start", {
+        title: "Start Exploration",
+        description: "Start an interactive exploration session on a connected device. For iOS, automatically starts WebDriverAgent (WDA) if not already running. Creates a persistent device connection for the LLM to explore the app UI before generating test cases. Returns a sessionId that must be passed to subsequent exploration_* tools. Session auto-expires after 30 minutes of inactivity.",
+        inputSchema: {
+            resourceId: z
+                .string()
+                .optional()
+                .describe("Device resource ID from list_devices (e.g., android:emulator-5554). If omitted, the first available device is used."),
+            appRef: z
+                .string()
+                .optional()
+                .describe("App to launch. Can be a bundleId (e.g., com.example.app) or an installable URL/path (.apk/.ipa). If omitted, the current app state is used."),
+        },
+    }, async (input) => jsonResult(await startHandler(input)));
+    // ---------------------------------------------------------------------------
+    // 2. exploration_end
+    // ---------------------------------------------------------------------------
+    server.registerTool("exploration_end", {
+        title: "End Exploration",
+        description: "End an exploration session and release the device connection. Always call this when done.",
+        inputSchema: {
+            sessionId: z.string().describe("Session ID from exploration_start"),
+        },
+    }, async (input) => jsonResult(await endHandler(input)));
+    // ---------------------------------------------------------------------------
+    // 3. exploration_get_page_summary
+    // ---------------------------------------------------------------------------
+    server.registerTool("exploration_get_page_summary", {
+        title: "Get Page Summary",
+        description: "Get a natural language summary of the current screen, including layout type (fixed single-screen / scrollable long page / multi-tab / list). Call this first when entering a new page to understand its structure before acting. Use this INSTEAD of ai_act if you just want to observe — ai_act is for changing state, not for looking around.",
+        inputSchema: {
+            sessionId: z.string().describe("Session ID from exploration_start"),
+        },
+    }, async (input) => jsonResult(await pageSummaryHandler(input)));
+    // ---------------------------------------------------------------------------
+    // 4. exploration_ask_about_screen
+    // ---------------------------------------------------------------------------
+    server.registerTool("exploration_ask_about_screen", {
+        title: "Ask About Screen",
+        description: "Ask a specific question about the current screen. Examples: 'What color is the submit button?'",
+        inputSchema: {
+            sessionId: z.string().describe("Session ID from exploration_start"),
+            question: z
+                .string()
+                .describe("Your question about the current screen"),
+        },
+    }, async (input) => jsonResult(await askHandler(input)));
+    // ---------------------------------------------------------------------------
+    // 5. exploration_ai_act
+    // ---------------------------------------------------------------------------
+    server.registerTool("exploration_ai_act", {
+        title: "AI Act",
+        description: "Perform a high-level UI interaction described in natural language. Examples: 'Go back', 'Tap the settings icon', 'Type text in the search box'. After execution, returns a summary of the new page state including whether the action actually changed anything.\n\nIMPORTANT: Use get_page_summary FIRST to check if the page is a fixed single-screen layout. If it is, do NOT request scroll actions — there is nothing to scroll to. Use ai_act only for meaningful interactions (tap, type, swipe between tabs), not for 'look around' or 'scroll to see more'. If the post-action summary reports that the page did not change, stop acting on this page and move on.",
+        inputSchema: {
+            sessionId: z.string().describe("Session ID from exploration_start"),
+            intent: z.string().describe("Description of what to do"),
+        },
+    }, async (input) => jsonResult(await actHandler(input)));
+    // ---------------------------------------------------------------------------
+    // 6. exploration_screenshot
+    // ---------------------------------------------------------------------------
+    server.registerTool("exploration_screenshot", {
+        title: "Take Screenshot",
+        description: "Take a screenshot of the current device screen and return it as base64.",
+        inputSchema: {
+            sessionId: z.string().describe("Session ID from exploration_start"),
+        },
+    }, async (input) => {
+        const { screenshot, mimeType } = await screenshotHandler(input);
+        return {
+            content: [
+                { type: "image", data: screenshot, mimeType },
+            ],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // 7. exploration_type
+    // ---------------------------------------------------------------------------
+    server.registerTool("exploration_type", {
+        title: "Type Text",
+        description: "Type text into the currently focused input field.",
+        inputSchema: {
+            sessionId: z.string().describe("Session ID from exploration_start"),
+            text: z.string().describe("The text to type"),
+        },
+    }, async (input) => jsonResult(await typeHandler(input)));
+    // ---------------------------------------------------------------------------
+    // 8. exploration_wait
+    // ---------------------------------------------------------------------------
+    server.registerTool("exploration_wait", {
+        title: "Wait",
+        description: "Wait for a specified duration in milliseconds (max 10000). Use after actions that trigger animations or page transitions.",
+        inputSchema: {
+            sessionId: z.string().describe("Session ID from exploration_start"),
+            ms: z
+                .number()
+                .int()
+                .min(0)
+                .max(10000)
+                .describe("Duration to wait in ms"),
+        },
+    }, async (input) => jsonResult(await waitHandler(input)));
+}

package/dist/mcp/exploration/sessionManager.js

@@ -0,0 +1,122 @@
+import { mkdir, readFile, writeFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+/**
+ * In-memory session store. If the MCP server process is restarted between
+ * tool calls, sessions are recovered from a backing JSON file on first access.
+ */
+const SESSIONS = new Map();
+// ---------------------------------------------------------------------------
+// File-based session metadata (survives MCP server restart)
+// ---------------------------------------------------------------------------
+function sessionsDir() {
+    return join(homedir(), ".preflight", "exploration-sessions");
+}
+function sessionFilePath(id) {
+    return join(sessionsDir(), `${id}.json`);
+}
+async function persistMeta(state, env) {
+    const dir = sessionsDir();
+    await mkdir(dir, { recursive: true });
+    const meta = {
+        id: state.id,
+        resourceId: state.resourceId,
+        platform: state.platform,
+        env,
+        createdAt: state.createdAt,
+        lastActivityAt: state.lastActivityAt,
+    };
+    await writeFile(sessionFilePath(state.id), JSON.stringify(meta, null, 2), "utf8");
+}
+export async function loadMeta(id) {
+    try {
+        const text = await readFile(sessionFilePath(id), "utf8");
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+async function removeMeta(id) {
+    try {
+        await unlink(sessionFilePath(id));
+    }
+    catch {
+        // ignore
+    }
+}
+// ---------------------------------------------------------------------------
+// Session lifecycle
+// ---------------------------------------------------------------------------
+/** Create a new exploration session and persist metadata to disk. */
+export function createSession(id, resourceId, platform, session, env) {
+    const state = {
+        id,
+        resourceId,
+        platform,
+        session,
+        createdAt: Date.now(),
+        lastActivityAt: Date.now(),
+    };
+    SESSIONS.set(id, state);
+    persistMeta(state, env).catch(() => { });
+    return state;
+}
+/**
+ * Get a session from memory. Throws if not found — caller should fall back
+ * to `restoreSession` for recovery across server restarts.
+ */
+export function getSession(id) {
+    const state = SESSIONS.get(id);
+    if (!state) {
+        throw new Error(`Exploration session not found: ${id}. Call exploration_start first.`);
+    }
+    if (Date.now() - state.lastActivityAt > SESSION_TIMEOUT_MS) {
+        void destroySession(state);
+        throw new Error(`Exploration session ${id} has expired (30 min timeout). Call exploration_start again.`);
+    }
+    state.lastActivityAt = Date.now();
+    return state;
+}
+/**
+ * Store a recreated session in memory (used by tools that recover from disk metadata).
+ */
+export function storeSession(id, session, meta) {
+    const state = {
+        id,
+        resourceId: meta.resourceId,
+        platform: meta.platform,
+        session,
+        createdAt: meta.createdAt,
+        lastActivityAt: Date.now(),
+    };
+    SESSIONS.set(id, state);
+    return state;
+}
+/** Destroy a session: remove from map + backing file, release device connection. */
+export async function destroySession(state) {
+    SESSIONS.delete(state.id);
+    await removeMeta(state.id);
+    try {
+        await state.session.device.destroy();
+    }
+    catch {
+        // ignore cleanup errors
+    }
+}
+/** Look up a session by ID and destroy it. No-op if session does not exist. */
+export async function destroySessionById(id) {
+    const state = SESSIONS.get(id);
+    if (!state) {
+        await removeMeta(id); // clean up orphaned meta
+        return;
+    }
+    await destroySession(state);
+}
+export function hasSession(id) {
+    return SESSIONS.has(id);
+}
+export function activeSessionCount() {
+    return SESSIONS.size;
+}