preflite 1.0.1

package/dist/infrastructure/transport/http/ResilientPlatformCallbackClient.js

@@ -0,0 +1,117 @@
+import { isCallbackNotFoundError, } from "./PlatformCallbackClient.js";
+/**
+ * HTTP 回调：主地址失败时可尝试备用地址；仍失败则落盘，可在网络恢复后 {@link flushOutbox} 重放。
+ */
+export class ResilientPlatformCallbackClient {
+    inner;
+    fallback;
+    outbox;
+    constructor(inner, fallback, outbox) {
+        this.inner = inner;
+        this.fallback = fallback;
+        this.outbox = outbox;
+    }
+    async flushOutbox() {
+        await this.outbox.processWith(this.inner, 100);
+    }
+    async pushTaskStatus(taskId, payload) {
+        let primaryErr;
+        try {
+            await this.inner.pushTaskStatus(taskId, payload);
+            return;
+        }
+        catch (e) {
+            primaryErr = e;
+        }
+        if (this.fallback) {
+            try {
+                await this.fallback.pushTaskStatus(taskId, payload);
+                return;
+            }
+            catch (e) {
+                if (isCallbackNotFoundError(primaryErr) && isCallbackNotFoundError(e)) {
+                    console.warn(`[ResilientPlatformCallbackClient] callback 404 on all URLs; skip outbox (taskId=${taskId})`);
+                    return;
+                }
+                await this.outbox.enqueue({ kind: "status", taskId, payload });
+                return;
+            }
+        }
+        if (isCallbackNotFoundError(primaryErr)) {
+            console.warn(`[ResilientPlatformCallbackClient] callback 404; skip outbox (taskId=${taskId})`);
+            return;
+        }
+        await this.outbox.enqueue({ kind: "status", taskId, payload });
+    }
+    async pushTaskLog(taskId, payload) {
+        let primaryErr;
+        try {
+            await this.inner.pushTaskLog(taskId, payload);
+            return;
+        }
+        catch (e) {
+            primaryErr = e;
+        }
+        if (this.fallback) {
+            try {
+                await this.fallback.pushTaskLog(taskId, payload);
+                return;
+            }
+            catch (e) {
+                if (isCallbackNotFoundError(primaryErr) && isCallbackNotFoundError(e)) {
+                    console.warn(`[ResilientPlatformCallbackClient] callback 404 on all URLs; skip outbox (taskId=${taskId})`);
+                    return;
+                }
+                await this.outbox.enqueue({ kind: "log", taskId, payload });
+                return;
+            }
+        }
+        if (isCallbackNotFoundError(primaryErr)) {
+            console.warn(`[ResilientPlatformCallbackClient] callback 404; skip outbox (taskId=${taskId})`);
+            return;
+        }
+        await this.outbox.enqueue({ kind: "log", taskId, payload });
+    }
+    async pushTaskReport(taskId, payload) {
+        let primaryErr;
+        try {
+            await this.inner.pushTaskReport(taskId, payload);
+            return;
+        }
+        catch (e) {
+            primaryErr = e;
+        }
+        const b64 = payload.reportBundleBase64;
+        if (b64 && b64.length > 4_000_000) {
+            console.warn("[ResilientPlatformCallbackClient] report too large to enqueue; drop outbox (taskId=" + taskId + ")");
+            return;
+        }
+        const dumpLen = payload.executionDumpJson?.length ?? 0;
+        const assetsLen = payload.reportAssetFiles?.reduce((acc, f) => acc + (typeof f.base64 === "string" ? f.base64.length : 0), 0) ?? 0;
+        if (dumpLen + assetsLen > 8_000_000) {
+            console.warn("[ResilientPlatformCallbackClient] execution dump payload too large to enqueue; drop outbox (taskId=" +
+                taskId +
+                ")");
+            return;
+        }
+        if (this.fallback) {
+            try {
+                await this.fallback.pushTaskReport(taskId, payload);
+                return;
+            }
+            catch (e) {
+                if (isCallbackNotFoundError(primaryErr) && isCallbackNotFoundError(e)) {
+                    console.warn(`[ResilientPlatformCallbackClient] callback 404 on all URLs; skip outbox (taskId=${taskId})`);
+                    return;
+                }
+                await this.outbox.enqueue({ kind: "report", taskId, payload });
+                return;
+            }
+        }
+        if (isCallbackNotFoundError(primaryErr)) {
+            console.warn(`[ResilientPlatformCallbackClient] callback 404; skip outbox (taskId=${taskId})`);
+            return;
+        }
+        await this.outbox.enqueue({ kind: "report", taskId, payload });
+    }
+}

package/dist/infrastructure/transport/midscenePaths.js

@@ -0,0 +1,28 @@
+import path from "node:path";
+export function resolveMidsceneRunDir(cwd, env = process.env) {
+    const base = env.MIDSCENE_RUN_DIR?.trim() || "midscene_run";
+    if (path.isAbsolute(base))
+        return base;
+    const agentHome = env.AGENT_HOME?.trim();
+    if (agentHome)
+        return path.resolve(agentHome, base);
+    return path.resolve(cwd, base);
+}
+/** 与 @midscene/shared 默认一致：run dir 下 `report`。 */
+export function getMidsceneReportRootDir(cwd, env = process.env) {
+    return path.join(resolveMidsceneRunDir(cwd, env), "report");
+}
+export function resolveTaskReportFilePaths(reportRoot, reportStem, outputFormat) {
+    if (outputFormat === "html-and-external-assets") {
+        const bundleDir = path.join(reportRoot, reportStem);
+        return {
+            reportName: reportStem,
+            reportHtmlPath: path.join(bundleDir, "index.html"),
+            bundleDir,
+        };
+    }
+    return {
+        reportName: `${reportStem}.html`,
+        reportHtmlPath: path.join(reportRoot, `${reportStem}.html`),
+    };
+}

package/dist/infrastructure/transport/ws/ResilientWsOrHttpEventPublisher.js

@@ -0,0 +1,29 @@
+/**
+ * WS 连通时仅走 WS；断开且配置了 HTTP ingest 时优先 POST，失败再回落到 WS 待发队列。
+ */
+export class ResilientWsOrHttpEventPublisher {
+    wsClient;
+    inner;
+    httpIngest;
+    constructor(wsClient, inner, httpIngest) {
+        this.wsClient = wsClient;
+        this.inner = inner;
+        this.httpIngest = httpIngest;
+    }
+    async publish(event) {
+        if (this.httpIngest.isEnabled() && !this.wsClient.isOpen()) {
+            try {
+                await this.httpIngest.postEvent(event);
+                return;
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                console.warn(`[ResilientWsOrHttpEventPublisher] HTTP ingest failed: ${msg}; buffering via WS`);
+            }
+        }
+        await this.inner.publish(event);
+    }
+    async publishLiveDebugFrame(event, frame) {
+        await this.inner.publishLiveDebugFrame(event, frame);
+    }
+}

package/dist/infrastructure/transport/ws/WsClient.js

@@ -0,0 +1,182 @@
+import WebSocket from "ws";
+function isBrokenPipeError(error) {
+    const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+    return code === "EPIPE" || code === "ECONNRESET" || code === "EHOSTUNREACH" || code === "ETIMEDOUT";
+}
+export class WsClient {
+    options;
+    socket = null;
+    heartbeatTimer = null;
+    reconnectTimer = null;
+    messageHandlers = [];
+    pendingSends = [];
+    reconnectAttempt = 0;
+    state = "disconnected";
+    constructor(options) {
+        this.options = options;
+    }
+    getConnectionState() {
+        return this.state;
+    }
+    isOpen() {
+        return this.socket !== null && this.socket.readyState === WebSocket.OPEN;
+    }
+    getPendingSendDepth() {
+        return this.pendingSends.length;
+    }
+    getReconnectAttempt() {
+        return this.reconnectAttempt;
+    }
+    setState(next) {
+        if (this.state === next)
+            return;
+        this.state = next;
+        this.options.onConnectionState?.(next);
+    }
+    onMessage(handler) {
+        this.messageHandlers.push(handler);
+    }
+    connect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.socket) {
+            try {
+                this.socket.removeAllListeners();
+                this.socket.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.socket = null;
+        }
+        this.setState("connecting");
+        this.socket = new WebSocket(this.options.endpoint, {
+            ...(this.options.authToken
+                ? { headers: { Authorization: `Bearer ${this.options.authToken}` } }
+                : {}),
+        });
+        this.socket.on("open", () => {
+            this.reconnectAttempt = 0;
+            this.setState("open");
+            this.startHeartbeat();
+            void this.flushPending();
+            this.options.onOpen?.();
+        });
+        this.socket.on("message", async (data) => {
+            const text = data.toString();
+            for (const handler of this.messageHandlers) {
+                await handler(text);
+            }
+        });
+        this.socket.on("close", () => this.scheduleReconnect());
+        this.socket.on("error", () => this.scheduleReconnect());
+    }
+    /**
+     * 发往平台 WS；对端已断开时常见 EPIPE/ECONNRESET。
+     * 此处永不 reject，避免业务层未捕获导致进程退出；失败时入队并关闭连接以触发重连。
+     */
+    async send(data) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+            this.pendingSends.push(data);
+            this.enforcePendingLimit();
+            this.options.onPendingDepth?.(this.pendingSends.length);
+            return;
+        }
+        const sock = this.socket;
+        await new Promise((resolve) => {
+            sock.send(data, (error) => {
+                if (error) {
+                    const code = error.code ?? "";
+                    const hint = isBrokenPipeError(error) ? " (peer likely closed connection)" : "";
+                    console.warn(`[WsClient] send failed code=${code}${hint}: ${error.message}`);
+                    this.pendingSends.unshift(data);
+                    this.enforcePendingLimit();
+                    this.options.onPendingDepth?.(this.pendingSends.length);
+                    try {
+                        sock.close();
+                    }
+                    catch {
+                        try {
+                            sock.terminate();
+                        }
+                        catch {
+                            /* ignore */
+                        }
+                    }
+                    resolve();
+                    return;
+                }
+                resolve();
+            });
+        });
+    }
+    enforcePendingLimit() {
+        const max = this.options.pendingQueueMaxItems ?? 10_000;
+        if (max <= 0 || this.pendingSends.length <= max)
+            return;
+        let dropped = 0;
+        while (this.pendingSends.length > max) {
+            this.pendingSends.shift();
+            dropped += 1;
+        }
+        if (dropped > 0) {
+            console.warn(`[WsClient] dropped ${dropped} pending send(s), maxQueue=${max}`);
+            this.options.onPendingDropped?.(dropped);
+        }
+    }
+    async flushPending() {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
+            return;
+        const queue = [...this.pendingSends];
+        this.pendingSends = [];
+        this.options.onPendingDepth?.(0);
+        for (const data of queue) {
+            await this.send(data);
+        }
+    }
+    startHeartbeat() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = setInterval(() => {
+            if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+                return;
+            }
+            try {
+                this.socket.ping();
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`[WsClient] ping failed: ${message}`);
+            }
+        }, this.options.heartbeatMs);
+    }
+    backoffDelayMs() {
+        const min = this.options.reconnectBackoffMinMs ??
+            (Number.isFinite(this.options.reconnectMs) && this.options.reconnectMs > 0 ? this.options.reconnectMs : 2000);
+        const maxCap = this.options.reconnectBackoffMaxMs ?? Math.max(min * 16, 60_000);
+        const exp = min * Math.pow(2, this.reconnectAttempt);
+        const capped = Math.min(maxCap, exp);
+        const jitter = Math.floor(Math.random() * Math.min(capped * 0.2, 5000));
+        return Math.min(maxCap, capped + jitter);
+    }
+    scheduleReconnect() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        // close / error / send 失败可能连续触发，合并为一次退避，避免 reconnectAttempt 连加
+        if (this.reconnectTimer) {
+            return;
+        }
+        this.setState("disconnected");
+        this.reconnectAttempt += 1;
+        const delayMs = this.backoffDelayMs();
+        this.options.onReconnectScheduled?.(delayMs, this.reconnectAttempt);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delayMs);
+    }
+}

package/dist/infrastructure/transport/ws/WsEventPublisher.js

@@ -0,0 +1,36 @@
+const LIVE_DEBUG_BINARY_MAGIC = "LDBG1";
+function encodeLiveDebugBinaryPacket(params) {
+    const header = Buffer.from(JSON.stringify({
+        kind: "LiveDebugFrameBinary",
+        sessionId: params.sessionId,
+        resourceId: params.resourceId,
+        mimeType: params.mimeType,
+        capturedAt: params.capturedAt,
+        byteLength: params.data.byteLength,
+        ...(params.foregroundApp ? { foregroundApp: params.foregroundApp } : {}),
+    }), "utf8");
+    const magic = Buffer.from(LIVE_DEBUG_BINARY_MAGIC, "utf8");
+    const headerLength = Buffer.allocUnsafe(4);
+    headerLength.writeUInt32BE(header.byteLength, 0);
+    return Buffer.concat([magic, headerLength, header, params.data]);
+}
+export class WsEventPublisher {
+    wsClient;
+    constructor(wsClient) {
+        this.wsClient = wsClient;
+    }
+    async publish(event) {
+        await this.wsClient.send(JSON.stringify(event));
+    }
+    async publishLiveDebugFrame(_event, frame) {
+        const packet = encodeLiveDebugBinaryPacket({
+            sessionId: frame.sessionId,
+            resourceId: frame.resourceId,
+            mimeType: frame.mimeType,
+            capturedAt: frame.capturedAt,
+            data: frame.data,
+            ...(frame.foregroundApp ? { foregroundApp: frame.foregroundApp } : {}),
+        });
+        await this.wsClient.send(packet);
+    }
+}

package/dist/interfaces/http/HttpServer.js

@@ -0,0 +1,227 @@
+import { createServer } from "node:http";
+import { LeaseConflictError } from "../../shared-kernel/errors/index.js";
+import { OwnerType } from "../../shared-kernel/enums/index.js";
+import { asLeaseId, asTaskId } from "../../shared-kernel/ids/index.js";
+export class HttpServer {
+    resourceService;
+    observationQueryService;
+    healthService;
+    port;
+    authToken;
+    agentId;
+    leaseService;
+    taskService;
+    appPackageService;
+    occupationRelease;
+    appPackageUrlCache;
+    constructor(resourceService, observationQueryService, healthService, port, authToken, agentId, leaseService, taskService, appPackageService, occupationRelease, appPackageUrlCache) {
+        this.resourceService = resourceService;
+        this.observationQueryService = observationQueryService;
+        this.healthService = healthService;
+        this.port = port;
+        this.authToken = authToken;
+        this.agentId = agentId;
+        this.leaseService = leaseService;
+        this.taskService = taskService;
+        this.appPackageService = appPackageService;
+        this.occupationRelease = occupationRelease;
+        this.appPackageUrlCache = appPackageUrlCache;
+    }
+    start() {
+        const server = createServer(async (req, res) => {
+            if (!req.url)
+                return this.writeJson(res, 404, { message: "not found" });
+            if (this.authToken) {
+                const auth = req.headers.authorization ?? "";
+                const expected = `Bearer ${this.authToken}`;
+                if (auth !== expected) {
+                    return this.writeJson(res, 401, { message: "unauthorized" });
+                }
+            }
+            const url = new URL(req.url, "http://127.0.0.1");
+            if (url.pathname === "/platform/commands" && req.method === "POST") {
+                return this.handlePlatformCommand(req, res);
+            }
+            if (url.pathname === "/health")
+                return this.writeJson(res, 200, this.healthService.snapshot());
+            if (url.pathname === "/metrics")
+                return this.writeJson(res, 200, this.healthService.snapshot());
+            if (url.pathname === "/cached-app-packages" && req.method === "GET") {
+                if (!this.appPackageUrlCache) {
+                    return this.writeJson(res, 503, { message: "app package url cache unavailable" });
+                }
+                const snap = await this.appPackageUrlCache.snapshotForHttp();
+                return this.writeJson(res, 200, snap);
+            }
+            if (url.pathname === "/resources") {
+                const forceRefresh = url.searchParams.get("refresh") !== "0";
+                if (forceRefresh) {
+                    await this.resourceService.refresh();
+                }
+                const resources = await this.resourceService.list();
+                if (!this.agentId)
+                    return this.writeJson(res, 200, resources);
+                return this.writeJson(res, 200, resources.map((item) => ({ ...item, agentId: this.agentId })));
+            }
+            const taskMatch = url.pathname.match(/^\/tasks\/([^/]+)$/);
+            if (taskMatch) {
+                const task = await this.observationQueryService.getTask(decodeURIComponent(taskMatch[1]));
+                if (!task)
+                    return this.writeJson(res, 404, { message: "task not found" });
+                return this.writeJson(res, 200, task);
+            }
+            const sessionMatch = url.pathname.match(/^\/sessions\/([^/]+)$/);
+            if (sessionMatch) {
+                const session = await this.observationQueryService.getSession(decodeURIComponent(sessionMatch[1]));
+                if (!session)
+                    return this.writeJson(res, 404, { message: "session not found" });
+                return this.writeJson(res, 200, session);
+            }
+            const leaseMatch = url.pathname.match(/^\/leases\/([^/]+)$/);
+            if (leaseMatch) {
+                const lease = await this.observationQueryService.getLease(decodeURIComponent(leaseMatch[1]));
+                if (!lease)
+                    return this.writeJson(res, 404, { message: "lease not found" });
+                return this.writeJson(res, 200, lease);
+            }
+            if (url.pathname === "/artifacts") {
+                const taskId = url.searchParams.get("taskId");
+                if (!taskId)
+                    return this.writeJson(res, 400, { message: "taskId is required" });
+                return this.writeJson(res, 200, await this.observationQueryService.listArtifacts(taskId));
+            }
+            if (url.pathname === "/events") {
+                const taskId = url.searchParams.get("taskId") ?? undefined;
+                const type = url.searchParams.get("type") ?? undefined;
+                const limit = Number(url.searchParams.get("limit") ?? "0");
+                return this.writeJson(res, 200, await this.observationQueryService.listEvents({
+                    taskId,
+                    type,
+                    limit: Number.isFinite(limit) ? limit : 0,
+                }));
+            }
+            return this.writeJson(res, 404, { message: "not found" });
+        });
+        server.listen(this.port);
+        return server;
+    }
+    readRequestBody(req) {
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            req.on("data", (c) => chunks.push(Buffer.from(c)));
+            req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+            req.on("error", reject);
+        });
+    }
+    async handlePlatformCommand(req, res) {
+        let raw = "";
+        try {
+            raw = await this.readRequestBody(req);
+        }
+        catch {
+            return this.writeJson(res, 400, { message: "invalid body" });
+        }
+        let parsed;
+        try {
+            parsed = raw.trim() ? JSON.parse(raw) : {};
+        }
+        catch {
+            return this.writeJson(res, 400, { message: "invalid json" });
+        }
+        const cmd = parsed && typeof parsed === "object" && "command" in parsed
+            ? parsed.command
+            : parsed;
+        if (!cmd || typeof cmd !== "object" || typeof cmd.type !== "string") {
+            return this.writeJson(res, 400, { message: "missing command.type" });
+        }
+        const cmdType = cmd.type;
+        const needsLeaseSvc = cmdType === "AcquireLeaseCommand" ||
+            cmdType === "ReleaseLeaseCommand" ||
+            cmdType === "RenewLeaseCommand" ||
+            cmdType === "RevokeLeaseByResourceCommand";
+        const needsTaskSvc = cmdType === "CreateTaskCommand" || cmdType === "CancelTaskCommand";
+        const needsAppPkgSvc = cmdType === "InstallAppCommand" || cmdType === "UninstallAppCommand";
+        if (needsLeaseSvc && !this.leaseService) {
+            return this.writeJson(res, 503, { message: "lease service unavailable" });
+        }
+        if (needsTaskSvc && !this.taskService) {
+            return this.writeJson(res, 503, { message: "task service unavailable" });
+        }
+        if (needsAppPkgSvc && !this.appPackageService) {
+            return this.writeJson(res, 503, { message: "app package service unavailable" });
+        }
+        try {
+            switch (cmd.type) {
+                case "AcquireLeaseCommand": {
+                    const c = cmd;
+                    const ot = c.ownerType;
+                    if (!Object.values(OwnerType).includes(ot)) {
+                        return this.writeJson(res, 400, { message: "invalid ownerType" });
+                    }
+                    await this.leaseService.acquire(c.leaseId, c.resourceId, c.ownerId, ot, c.ttlSeconds, {
+                        username: c.occupantUsername,
+                        displayName: c.occupantDisplayName,
+                    });
+                    return this.writeJson(res, 200, { ok: true });
+                }
+                case "ReleaseLeaseCommand": {
+                    const c = cmd;
+                    await this.leaseService.release(asLeaseId(c.leaseId));
+                    return this.writeJson(res, 200, { ok: true });
+                }
+                case "RenewLeaseCommand": {
+                    const c = cmd;
+                    await this.leaseService.renew(asLeaseId(c.leaseId), c.ttlSeconds);
+                    return this.writeJson(res, 200, { ok: true });
+                }
+                case "RevokeLeaseByResourceCommand": {
+                    const c = cmd;
+                    if (this.occupationRelease) {
+                        await this.occupationRelease.forceRelease(c.resourceId);
+                    }
+                    else {
+                        await this.leaseService.revokeByResourceId(c.resourceId);
+                    }
+                    return this.writeJson(res, 200, { ok: true });
+                }
+                case "CreateTaskCommand": {
+                    const c = cmd;
+                    void this.taskService.dispatch(c).catch((error) => {
+                        const message = error instanceof Error ? error.message : String(error);
+                        console.error(`[HttpServer] CreateTaskCommand dispatch failed: ${message}`);
+                    });
+                    return this.writeJson(res, 202, { ok: true, accepted: true });
+                }
+                case "CancelTaskCommand": {
+                    const c = cmd;
+                    await this.taskService.cancel(asTaskId(c.taskId));
+                    return this.writeJson(res, 200, { ok: true });
+                }
+                case "InstallAppCommand": {
+                    const c = cmd;
+                    await this.appPackageService.install(c.resourceId, c.appRef);
+                    return this.writeJson(res, 200, { ok: true });
+                }
+                case "UninstallAppCommand": {
+                    const c = cmd;
+                    await this.appPackageService.uninstall(c.resourceId, c.bundleId);
+                    return this.writeJson(res, 200, { ok: true });
+                }
+                default:
+                    return this.writeJson(res, 400, { message: `unsupported command: ${cmd.type}` });
+            }
+        }
+        catch (error) {
+            if (error instanceof LeaseConflictError) {
+                return this.writeJson(res, 409, { ok: false, message: error.message, resourceId: error.resourceId });
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            return this.writeJson(res, 500, { ok: false, message });
+        }
+    }
+    writeJson(res, statusCode, data) {
+        res.statusCode = statusCode;
+        res.setHeader("Content-Type", "application/json; charset=utf-8");
+        res.end(JSON.stringify(data));
+    }
+}