@autifyhq/aximo-cli 0.9.0 → 0.10.1

package/README.md

@@ -623,7 +623,7 @@ claude mcp add aximo -- aximo mcp
 
 VS Code (Copilot agent mode) uses the same entry under a `servers` key in `.vscode/mcp.json`.
 
-The server exposes 16 tools: 10 read-only ones for inspecting sessions and cases (`aximo_get_session_timeline` is the load-bearing one for Playwright export) plus 6 that author content (create and delete cases, create plans, save a session as a case). See the [MCP reference](./skills/aximo-cli/references/mcp.md) for per-client config paths, the full tool table, the Playwright export prompt, and a no-client smoke test.
+The server exposes 18 tools: 12 read-only ones for inspecting sessions, cases, and plan runs (`aximo_get_session_timeline` is the load-bearing one for Playwright export; `aximo_list_plan_runs` and `aximo_get_plan_run` cover run-status polling) plus 6 that author content (create and delete cases, create plans, save a session as a case). See the [MCP reference](./skills/aximo-cli/references/mcp.md) for per-client config paths, the full tool table, the Playwright export prompt, and a no-client smoke test.
 
 ## Agent Skills
 

package/dist/commands/device/connect.js

@@ -1,5 +1,5 @@
-import { defineCommand } from "citty";
 import { existsSync, readFileSync } from "node:fs";
+import { defineCommand } from "citty";
 import { getBaseUrl } from "../../client.js";
 import { formatError, printResult } from "../../output.js";
 import { getDeviceConfigPath } from "./paths.js";
@@ -29,10 +29,28 @@ function getRelayUrl() {
 }
 async function connectToRelay(config) {
     const { ensurePythonReady, startDesktopRemote } = await import("../../desktop-server/setup.js");
+    const { confirmProceed, formatPreflightLines, runLocalPreflight } = await import("../../desktop-server/preflight.js");
     console.log("Preparing Python environment...");
     const { pythonPath, scriptPath, agentVersion } = await ensurePythonReady();
     console.log(`Python ready: ${pythonPath}`);
     console.log(`Agent version: ${agentVersion}`);
+    // Last point where a human is present: sessions are triggered remotely, so this
+    // is the only place a failed check can offer to stop before it wastes a run.
+    const preflight = runLocalPreflight({ pythonPath, scriptPath });
+    if (preflight.kind === "ok") {
+        for (const line of formatPreflightLines(preflight.report))
+            console.log(line);
+        if (!(await confirmProceed(preflight.report))) {
+            console.log("Not connecting. Fix the checks above and run 'aximo device connect' again.");
+            return;
+        }
+    }
+    else if (preflight.kind === "error") {
+        console.log(`Desktop environment: could not be checked (${preflight.detail}).`);
+    }
+    else {
+        console.log("Desktop environment: checks unavailable for this agent version.");
+    }
     const relayUrl = getRelayUrl();
     console.log(`Starting desktop agent, relay: ${relayUrl}`);
     let remoteProcess = startDesktopRemote(pythonPath, scriptPath, {

package/dist/commands/device/doctor.d.ts

@@ -1,4 +1,5 @@
 import { type ClientDeps } from "../../client.js";
+import { type LocalPreflight } from "../../desktop-server/preflight.js";
 import type { Envelope } from "../../types.js";
 export type CheckStatus = "pass" | "warn" | "fail" | "info";
 export interface Check {
@@ -30,6 +31,7 @@ export interface AgentTlsDeps {
     probe?: (host: string, port: number, ca: Buffer) => Promise<TlsProbeResult>;
 }
 export declare function checkAgentTlsTrust(deps?: AgentTlsDeps): Promise<Check>;
+export declare function checkDesktopEnvironment(runPreflight?: () => LocalPreflight): Check[];
 export interface RunDoctorOptions {
     skipRelay?: boolean;
     skipApi?: boolean;

package/dist/commands/device/doctor.js

@@ -7,6 +7,7 @@ import { WebSocket } from "ws";
 import { getBaseUrl, request } from "../../client.js";
 import { loadConfig } from "../../config.js";
 import { readCachedManifest } from "../../desktop-server/agent-sync.js";
+import { runLocalPreflight } from "../../desktop-server/preflight.js";
 import { installedPythonTag, PYTHON_RELEASE, PYTHON_VERSION } from "../../desktop-server/setup.js";
 import { formatSuccess, printResult } from "../../output.js";
 import { readDeviceConfig } from "./device-config.js";
@@ -450,6 +451,41 @@ async function checkCurrentStatus(deviceId, deps) {
         };
     }
 }
+// The desktop agent is the only thing that can see the tester's screen, input
+// source and permissions, so doctor reports what it reports rather than
+// reimplementing the probes here.
+const MANUAL_DESKTOP_HINT = {
+    darwin: "Grant Accessibility + Screen Recording in System Settings → Privacy & Security",
+    win32: "Run from an elevated terminal if the test touches admin windows",
+    linux: "Use an X11/Xorg session; Wayland blocks capture and synthetic input",
+};
+export function checkDesktopEnvironment(runPreflight = runLocalPreflight) {
+    const result = runPreflight();
+    if (result.kind === "ok") {
+        return result.report.checks.map((check) => ({ ...check, name: `desktop: ${check.name}` }));
+    }
+    const hint = MANUAL_DESKTOP_HINT[platform()];
+    if (result.kind === "error") {
+        return [
+            {
+                name: "desktop environment",
+                status: "fail",
+                message: `the agent could not check this machine: ${result.detail}`,
+                hint: "Run: aximo device reset --deps && aximo device setup",
+            },
+        ];
+    }
+    return [
+        {
+            name: "desktop environment",
+            status: "info",
+            message: "not checked — the agent is not installed yet",
+            ...(hint
+                ? { hint: `Run: aximo device setup. ${hint}` }
+                : { hint: "Run: aximo device setup" }),
+        },
+    ];
+}
 function checkPlatformExtras() {
     const p = platform();
     if (p === "linux") {
@@ -468,16 +504,6 @@ function checkPlatformExtras() {
             },
         ];
     }
-    if (p === "darwin") {
-        return [
-            {
-                name: "macos permissions",
-                status: "info",
-                message: "Accessibility + Screen Recording must be granted manually",
-                hint: "System Settings → Privacy & Security → Accessibility / Screen Recording",
-            },
-        ];
-    }
     return [];
 }
 function logDirUsage() {
@@ -509,6 +535,7 @@ export async function runDeviceDoctor(options = {}, deps) {
     checks.push(checkPythonDeps());
     checks.push(checkAgentFiles());
     checks.push(...checkPlatformExtras());
+    checks.push(...checkDesktopEnvironment());
     checks.push(logDirUsage());
     if (!options.skipApi && checks[0]?.status !== "fail") {
         checks.push(await checkAgentUpToDate(deps));

package/dist/commands/device/doctor.test.js

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { HttpResponse, http, server, TEST_BASE_URL } from "../../test-utils.js";
-import { checkAgentTlsTrust, relayProbeUrl, runDeviceDoctor } from "./doctor.js";
+import { checkAgentTlsTrust, checkDesktopEnvironment, relayProbeUrl, runDeviceDoctor, } from "./doctor.js";
 let tempHome;
 beforeAll(() => {
     tempHome = mkdtempSync(join(tmpdir(), "aximo-doctor-"));
@@ -153,3 +153,28 @@ describe("checkAgentTlsTrust", () => {
         expect(c.message).toContain("missing file");
     });
 });
+describe("checkDesktopEnvironment", () => {
+    const REPORT = {
+        agent: { platform: "Darwin" },
+        checks: [
+            { name: "accessibility permission", status: "fail", message: "not granted" },
+            { name: "capture target", status: "info", message: "capturing the primary monitor" },
+        ],
+    };
+    it("reports what the agent found, namespaced so its checks are distinguishable", () => {
+        const checks = checkDesktopEnvironment(() => ({ kind: "ok", report: REPORT }));
+        expect(checks.map((c) => c.name)).toEqual([
+            "desktop: accessibility permission",
+            "desktop: capture target",
+        ]);
+        expect(checks[0]?.status).toBe("fail");
+    });
+    // Before `aximo device setup` there is no agent to ask, so doctor still has to
+    // say something useful rather than claim the desktop is fine.
+    it("falls back to a manual note when the agent cannot be run", () => {
+        const checks = checkDesktopEnvironment(() => ({ kind: "not-installed" }));
+        expect(checks).toHaveLength(1);
+        expect(checks[0]?.status).toBe("info");
+        expect(checks[0]?.hint ?? checks[0]?.message).toContain(process.platform === "darwin" ? "System Settings" : "aximo device setup");
+    });
+});

package/dist/commands/mcp/server.test.js

@@ -24,7 +24,7 @@ async function connect() {
     };
 }
 describe("createMcpServer wiring", () => {
-    it("exposes all 16 tools through tools/list with valid JSON Schema", async () => {
+    it("exposes all 18 tools through tools/list with valid JSON Schema", async () => {
         const { client, cleanup } = await connect();
         try {
             const { tools } = await client.listTools();
@@ -44,6 +44,8 @@ describe("createMcpServer wiring", () => {
                 "aximo_create_plan",
                 "aximo_add_case_to_plan",
                 "aximo_remove_case_from_plan",
+                "aximo_list_plan_runs",
+                "aximo_get_plan_run",
                 "aximo_save_session_as_case",
             ].sort());
             const timeline = tools.find((t) => t.name === "aximo_get_session_timeline");

package/dist/commands/mcp/tools.js

@@ -260,6 +260,34 @@ export function defineTools(deps = {}) {
                 return await request(`/api/plans/${encodeURIComponent(planId)}/cases/${encodeURIComponent(caseId)}`, { method: "DELETE" }, deps);
             }),
         },
+        {
+            name: "aximo_list_plan_runs",
+            title: "List plan runs",
+            description: "List a plan's runs, newest first, without per-case detail. Use aximo_get_plan_run for one run's per-case breakdown. Paginate by passing the previous page's nextCursor as cursor. A run's status reflects execution, not the test verdict: read passedCases/failedCases to judge outcomes.",
+            inputSchema: {
+                planId: z.string().uuid(),
+                limit: z.number().int().positive().max(50).optional(),
+                cursor: z
+                    .string()
+                    .optional()
+                    .describe("nextCursor from the previous page (ISO 8601 createdAt of its last run)."),
+            },
+            handler: async ({ planId, ...rest }) => call(async () => {
+                return await request(`/api/triggers/plans/${encodeURIComponent(planId)}/runs`, { query: buildQuery(rest) }, deps);
+            }),
+        },
+        {
+            name: "aximo_get_plan_run",
+            title: "Get plan run status",
+            description: "Get the overall status and per-case breakdown of a plan run (from aximo_list_plan_runs, or the planRunId returned when a run was triggered). Poll this to observe a run in progress; wait at least 5 seconds between polls. A run's status reflects execution, not the test verdict: a run can complete with failedCases > 0, so read passedCases/failedCases and the per-case statuses to judge outcomes.",
+            inputSchema: {
+                planId: z.string().uuid(),
+                planRunId: z.string().uuid(),
+            },
+            handler: async ({ planId, planRunId }) => call(async () => {
+                return await request(`/api/triggers/plans/${encodeURIComponent(planId)}/runs/${encodeURIComponent(planRunId)}`, {}, deps);
+            }),
+        },
         {
             name: "aximo_save_session_as_case",
             title: "Save session as test case",

package/dist/commands/mcp/tools.test.js

@@ -36,6 +36,8 @@ describe("defineTools", () => {
             "aximo_create_plan",
             "aximo_add_case_to_plan",
             "aximo_remove_case_from_plan",
+            "aximo_list_plan_runs",
+            "aximo_get_plan_run",
             "aximo_save_session_as_case",
         ]);
     });
@@ -141,6 +143,94 @@ describe("aximo_list_projects", () => {
         expect(new URL(captured.url).pathname).toBe("/api/organizations/projects");
     });
 });
+describe("aximo_list_plan_runs", () => {
+    const planId = "77777777-7777-4777-9777-777777777777";
+    it("calls /api/triggers/plans/:id/runs, passing limit and cursor through", async () => {
+        let url = null;
+        const payload = {
+            items: [
+                {
+                    id: "88888888-8888-4888-9888-888888888888",
+                    status: "succeeded",
+                    triggerSource: "api",
+                    executionMode: "parallel",
+                    totalCases: 3,
+                    completedCases: 3,
+                    passedCases: 2,
+                    failedCases: 1,
+                    startedAt: "2026-07-01T00:00:00.000Z",
+                    completedAt: "2026-07-01T00:10:00.000Z",
+                    createdAt: "2026-07-01T00:00:00.000Z",
+                },
+            ],
+            nextCursor: "2026-07-01T00:00:00.000Z",
+        };
+        server.use(http.get(`${TEST_BASE_URL}/api/triggers/plans/${planId}/runs`, ({ request: req }) => {
+            url = new URL(req.url);
+            return HttpResponse.json(payload);
+        }));
+        const tool = byName(defineTools(), "aximo_list_plan_runs");
+        const result = await tool.handler({
+            planId,
+            limit: 5,
+            cursor: "2026-07-02T00:00:00.000Z",
+        });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+        expect(url).not.toBeNull();
+        expect(url.searchParams.get("limit")).toBe("5");
+        expect(url.searchParams.get("cursor")).toBe("2026-07-02T00:00:00.000Z");
+    });
+    it("preserves the backend's 404 for an unknown plan", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/triggers/plans/${planId}/runs`, () => HttpResponse.json({ error: "Test plan not found" }, { status: 404 })));
+        const tool = byName(defineTools(), "aximo_list_plan_runs");
+        const result = await tool.handler({ planId });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result).error).toBe("Test plan not found");
+    });
+});
+describe("aximo_get_plan_run", () => {
+    const planId = "77777777-7777-4777-9777-777777777777";
+    const planRunId = "99999999-9999-4999-9999-999999999999";
+    it("calls /api/triggers/plans/:id/runs/:runId and returns the run with cases", async () => {
+        const payload = {
+            id: planRunId,
+            status: "succeeded",
+            triggerSource: "api",
+            executionMode: "sequential",
+            totalCases: 1,
+            completedCases: 1,
+            passedCases: 0,
+            failedCases: 1,
+            startedAt: "2026-07-01T00:00:00.000Z",
+            completedAt: "2026-07-01T00:05:00.000Z",
+            createdAt: "2026-07-01T00:00:00.000Z",
+            cases: [
+                {
+                    id: "aaaaaaaa-aaaa-4aaa-9aaa-aaaaaaaaaaaa",
+                    caseId: "bbbbbbbb-bbbb-4bbb-9bbb-bbbbbbbbbbbb",
+                    title: "Login flow",
+                    type: "web",
+                    status: "failed",
+                    startedAt: "2026-07-01T00:00:10.000Z",
+                    completedAt: "2026-07-01T00:04:40.000Z",
+                },
+            ],
+        };
+        server.use(http.get(`${TEST_BASE_URL}/api/triggers/plans/${planId}/runs/${planRunId}`, () => HttpResponse.json(payload)));
+        const tool = byName(defineTools(), "aximo_get_plan_run");
+        const result = await tool.handler({ planId, planRunId });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+    });
+    it("preserves the backend's 404 for an unknown run id", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/triggers/plans/${planId}/runs/${planRunId}`, () => HttpResponse.json({ error: "Plan run not found" }, { status: 404 })));
+        const tool = byName(defineTools(), "aximo_get_plan_run");
+        const result = await tool.handler({ planId, planRunId });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result).error).toBe("Plan run not found");
+    });
+});
 describe("call() error mapping", () => {
     const sessionId = "66666666-6666-4666-9666-666666666666";
     it("maps 403 with the original message and a hint", async () => {

package/dist/commands/mobile/connect-core.d.ts

@@ -1,5 +1,5 @@
 import type { ErrorEnvelope } from "../../types.js";
-import type { MobileController } from "../../mobile-control/controller.js";
+import { AppiumController } from "../../mobile-control/appium-controller.js";
 import { type IosSigningConfig } from "../../mobile-control/ios-signing.js";
 import { type MobileDeviceConfig } from "./paths.js";
 export declare function getTunnelOrigin(): string;
@@ -8,7 +8,7 @@ interface ConfigOk {
     config: MobileDeviceConfig;
 }
 export declare function resolveDeviceConfig(deviceId: string | undefined): ConfigOk | ErrorEnvelope;
-export declare function buildController(config: MobileDeviceConfig, endpoint: string, iosSigning?: IosSigningConfig, wdaLocalPort?: number | (() => Promise<number>)): MobileController;
+export declare function buildController(config: MobileDeviceConfig, endpoint: string, iosSigning?: IosSigningConfig, wdaLocalPort?: number | (() => Promise<number>), mjpegServerPort?: number | (() => Promise<number>)): AppiumController;
 export declare function connectWithConfig(config: MobileDeviceConfig, options?: {
     assumeYes?: boolean;
 }): Promise<void>;

package/dist/commands/mobile/connect-core.js

@@ -4,6 +4,8 @@ import { AppiumController } from "../../mobile-control/appium-controller.js";
 import { installUploadedApp } from "../../mobile-control/app-install.js";
 import { pickFreePort, startAppiumServer } from "../../mobile-control/appium-server.js";
 import { withBundleIdTranslation } from "../../mobile-control/bundle-id-map.js";
+import { FrameSender } from "../../mobile-control/frame-sender.js";
+import { MjpegStreamClient } from "../../mobile-control/mjpeg-stream.js";
 import { getIosDeviceInfo, iosMajorVersion } from "../../mobile-control/ios-devicectl.js";
 import { ensureIosTunnel, TUNNEL_STOP_COMMAND } from "../../mobile-control/ios-tunnel.js";
 import { resolveIosSigning, resolveIosSigningAuto, } from "../../mobile-control/ios-signing.js";
@@ -38,11 +40,12 @@ export function resolveDeviceConfig(deviceId) {
     }
     return { ok: true, config: only };
 }
-export function buildController(config, endpoint, iosSigning, wdaLocalPort) {
+export function buildController(config, endpoint, iosSigning, wdaLocalPort, mjpegServerPort) {
     return new AppiumController({
         endpoint,
         platform: config.platform,
         target: config.target,
+        ...(mjpegServerPort ? { mjpegServerPort } : {}),
         ...(config.platform === "ios"
             ? { iosSigning: iosSigning ?? resolveIosSigning(), ...(wdaLocalPort ? { wdaLocalPort } : {}) }
             : {}),
@@ -160,10 +163,35 @@ export async function connectWithConfig(config, options) {
     }
     // Re-signing can remap bundle ids; launches from the backend use the original.
     const installedBundleIds = new Map();
-    const rawController = buildController(config, server.endpoint, iosSigning, wdaLocalPort);
+    const rawController = buildController(config, server.endpoint, iosSigning, wdaLocalPort, pickFreePort);
     const controller = config.platform === "ios"
         ? withBundleIdTranslation(rawController, installedBundleIds)
         : rawController;
+    // Live-view pipeline: capture (device MJPEG server -> local socket) feeds the
+    // sender (dedicated tunnel connection -> gateway). Started/stopped on demand
+    // by the gateway; frame acks reporting "no viewers" also stop it.
+    const frameSender = new FrameSender({
+        wsUrl: getTunnelOrigin(),
+        deviceToken: config.deviceToken,
+        onInactive: () => stream.stop(),
+        log: (message) => console.error(message),
+    });
+    const streamClient = new MjpegStreamClient({
+        ensureReady: () => rawController.ensureReady(),
+        getPort: () => rawController.getMjpegPort(),
+        onFrame: (frame) => frameSender.push(frame),
+        log: (message) => console.error(message),
+    });
+    const stream = {
+        start: () => {
+            frameSender.start();
+            streamClient.start();
+        },
+        stop: () => {
+            void streamClient.stop();
+            frameSender.stop();
+        },
+    };
     try {
         // Warm up the device session before connecting to Aximo so WDA build/signing/
         // trust problems surface here — with a clear, actionable message — instead of
@@ -178,6 +206,7 @@ export async function connectWithConfig(config, options) {
             deviceToken: config.deviceToken,
             deviceName: config.name,
             controller,
+            stream,
             installApp: async ({ uploadId }) => {
                 const result = await installUploadedApp({
                     uploadId,
@@ -196,6 +225,10 @@ export async function connectWithConfig(config, options) {
         });
     }
     finally {
+        // Await the capture loop before tearing down the controller/server so a
+        // mid-flight ensureReady/stream read can't race the Appium session close.
+        frameSender.stop();
+        await streamClient.stop();
         await controller.close();
         await server.stop();
         if (tunnelRunning) {

package/dist/commands/mobile/signing-consent.js

@@ -1,8 +1,4 @@
-import { createInterface } from "node:readline/promises";
-function defaultAsk(question) {
-    const rl = createInterface({ input: process.stdin, output: process.stderr });
-    return rl.question(question).finally(() => rl.close());
-}
+import { confirmYesNo } from "../../prompt.js";
 /**
  * Informed consent before using the user's Apple signing identity: connecting
  * can re-sign apps/WDA with it, register the device to the team's Apple
@@ -19,10 +15,8 @@ export async function confirmIosSigning(options) {
         "Set AXIMO_IOS_TEAM_ID to sign with a different team.");
     if (options.assumeYes)
         return true;
-    const interactive = options.interactive ?? process.stdin.isTTY === true;
-    if (!interactive)
-        return true;
-    const ask = options.ask ?? defaultAsk;
-    const answer = (await ask("Proceed with this signing identity? [Y/n] ")).trim().toLowerCase();
-    return answer !== "n" && answer !== "no";
+    return confirmYesNo("Proceed with this signing identity?", {
+        ...(options.interactive === undefined ? {} : { interactive: options.interactive }),
+        ...(options.ask ? { ask: options.ask } : {}),
+    });
 }

package/dist/desktop-server/preflight.d.ts

@@ -0,0 +1,43 @@
+import { type SpawnSyncReturns } from "node:child_process";
+import type { Check } from "../commands/device/doctor.js";
+export interface PreflightReport {
+    agent?: {
+        platform?: string;
+    };
+    checks: Check[];
+}
+/**
+ * Either the agent's report, "there is no agent to ask yet", or "the agent is
+ * installed but could not answer". Keeping the last two apart matters: doctor
+ * must not tell a tester their machine is fine, or unconfigured, when the probe
+ * actually crashed.
+ */
+export type LocalPreflight = {
+    kind: "ok";
+    report: PreflightReport;
+} | {
+    kind: "not-installed";
+} | {
+    kind: "error";
+    detail: string;
+};
+export type SpawnSyncFn = (command: string, args: string[], options: {
+    encoding: "utf-8";
+    timeout: number;
+    env: NodeJS.ProcessEnv;
+}) => SpawnSyncReturns<string>;
+export interface LocalPreflightOptions {
+    pythonPath?: string;
+    scriptPath?: string;
+    spawn?: SpawnSyncFn;
+}
+/** Run the desktop agent's own environment checks without connecting to a gateway. */
+export declare function runLocalPreflight(options?: LocalPreflightOptions): LocalPreflight;
+export declare function formatPreflightLines(report: PreflightReport): string[];
+export declare function hasBlockingChecks(report: PreflightReport): boolean;
+export interface ConfirmProceedOptions {
+    interactive?: boolean;
+    ask?: (question: string) => Promise<string>;
+}
+/** Ask whether to continue past a failed check, but only when there is one. */
+export declare function confirmProceed(report: PreflightReport, options?: ConfirmProceedOptions): Promise<boolean>;

package/dist/desktop-server/preflight.js

@@ -0,0 +1,78 @@
+import { spawnSync as nodeSpawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { getAgentScriptPath, getAximoDir, getEmbeddedPythonBinary, } from "../commands/device/paths.js";
+import { confirmYesNo } from "../prompt.js";
+const PREFLIGHT_TIMEOUT_MS = 20_000;
+const STATUSES = ["pass", "warn", "fail", "info"];
+function isCheck(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const check = value;
+    return (typeof check["name"] === "string" &&
+        typeof check["message"] === "string" &&
+        STATUSES.includes(check["status"]));
+}
+function parseReport(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const checks = parsed["checks"];
+    if (!Array.isArray(checks) || !checks.every(isCheck))
+        return null;
+    return parsed;
+}
+function firstLine(text) {
+    return text.trim().split("\n")[0]?.trim() ?? "";
+}
+/** Run the desktop agent's own environment checks without connecting to a gateway. */
+export function runLocalPreflight(options = {}) {
+    const pythonPath = options.pythonPath ?? getEmbeddedPythonBinary();
+    const scriptPath = options.scriptPath ?? getAgentScriptPath();
+    if (!existsSync(pythonPath) || !existsSync(scriptPath))
+        return { kind: "not-installed" };
+    const spawn = options.spawn ?? nodeSpawnSync;
+    const result = spawn(pythonPath, [scriptPath, "--preflight"], {
+        encoding: "utf-8",
+        timeout: PREFLIGHT_TIMEOUT_MS,
+        env: { ...process.env, AXIMO_HOME: getAximoDir() },
+    });
+    if (result.status !== 0) {
+        // An agent script older than --preflight exits on the missing GATEWAY_URL.
+        const stderr = firstLine(result.stderr ?? "");
+        if (stderr.includes("GATEWAY_URL"))
+            return { kind: "not-installed" };
+        return { kind: "error", detail: stderr || `exited with status ${result.status}` };
+    }
+    const report = parseReport(result.stdout ?? "");
+    if (!report)
+        return { kind: "error", detail: "the agent did not return a readable report" };
+    return { kind: "ok", report };
+}
+const STATUS_MARK = {
+    pass: "✔",
+    warn: "!",
+    fail: "✘",
+    info: "·",
+};
+export function formatPreflightLines(report) {
+    const lines = report.checks.map((check) => {
+        const hint = check.hint ? `\n    → ${check.hint}` : "";
+        return `  ${STATUS_MARK[check.status]} ${check.name}: ${check.message}${hint}`;
+    });
+    return ["Desktop environment:", ...lines];
+}
+export function hasBlockingChecks(report) {
+    return report.checks.some((check) => check.status === "warn" || check.status === "fail");
+}
+/** Ask whether to continue past a failed check, but only when there is one. */
+export async function confirmProceed(report, options = {}) {
+    if (!hasBlockingChecks(report))
+        return true;
+    return confirmYesNo("Proceed anyway?", options);
+}

package/dist/desktop-server/preflight.test.d.ts

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