@autifyhq/aximo-cli 0.10.1 → 0.11.0

package/dist/desktop-server/setup-deps.test.js

@@ -0,0 +1,112 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { getDepsMarkerPath } from "../commands/device/paths.js";
+import { ensureDependencies, pipInstallArgs } from "./setup.js";
+let tempDir;
+let requirements;
+const savedEnv = {};
+beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "aximo-deps-"));
+    savedEnv["AXIMO_HOME"] = process.env["AXIMO_HOME"];
+    process.env["AXIMO_HOME"] = tempDir;
+    requirements = join(tempDir, "requirements.txt");
+    writeFileSync(requirements, "pyautogui>=0.9.54\n");
+});
+afterEach(() => {
+    for (const [key, value] of Object.entries(savedEnv)) {
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+    rmSync(tempDir, { recursive: true, force: true });
+});
+describe("pipInstallArgs", () => {
+    it("resolves from PyPI when no wheel directory is given", () => {
+        const args = pipInstallArgs("/tmp/requirements.txt");
+        expect(args).toEqual([
+            "-m",
+            "pip",
+            "install",
+            "--disable-pip-version-check",
+            "--no-warn-script-location",
+            "-r",
+            "/tmp/requirements.txt",
+        ]);
+    });
+    it("pins pip to a local wheel directory and blocks the index entirely", () => {
+        const args = pipInstallArgs("/tmp/requirements.txt", "/payload/wheels");
+        expect(args).toContain("--no-index");
+        expect(args.slice(args.indexOf("--find-links"), args.indexOf("--find-links") + 2)).toEqual([
+            "--find-links",
+            "/payload/wheels",
+        ]);
+        // -r must still come last so the requirements file drives resolution.
+        expect(args.slice(-2)).toEqual(["-r", "/tmp/requirements.txt"]);
+    });
+});
+describe("ensureDependencies", () => {
+    it("installs offline and records the requirements hash", () => {
+        const calls = [];
+        ensureDependencies("/py", requirements, {
+            wheelsDir: "/payload/wheels",
+            exec: (_file, args) => {
+                calls.push(args);
+                return { status: 0 };
+            },
+        });
+        expect(calls).toHaveLength(1);
+        expect(calls[0]).toContain("--no-index");
+        expect(existsSync(getDepsMarkerPath())).toBe(true);
+    });
+    it("skips the install when the requirements have not changed", () => {
+        let runs = 0;
+        const exec = () => {
+            runs++;
+            return { status: 0 };
+        };
+        ensureDependencies("/py", requirements, { exec });
+        ensureDependencies("/py", requirements, { exec });
+        expect(runs).toBe(1);
+    });
+    it("reinstalls when the requirements change", () => {
+        let runs = 0;
+        const exec = () => {
+            runs++;
+            return { status: 0 };
+        };
+        ensureDependencies("/py", requirements, { exec });
+        writeFileSync(requirements, "pyautogui>=0.9.54\nmss>=10.0\n");
+        ensureDependencies("/py", requirements, { exec });
+        expect(runs).toBe(2);
+    });
+    it("blames a stale payload when an offline install cannot be satisfied", () => {
+        expect(() => ensureDependencies("/py", requirements, {
+            wheelsDir: "/payload/wheels",
+            exec: () => ({ status: 1 }),
+        })).toThrow(/older than the requirements/);
+    });
+    it("names the wheel directory in the offline failure so it can be checked", () => {
+        expect(() => ensureDependencies("/py", requirements, {
+            wheelsDir: "/payload/wheels",
+            exec: () => ({ status: 1 }),
+        })).toThrow(/\/payload\/wheels/);
+    });
+    it("keeps the plain failure message for an online install", () => {
+        expect(() => ensureDependencies("/py", requirements, { exec: () => ({ status: 1 }) })).toThrow(/^pip install failed \(exit 1\)$/);
+    });
+    it("does not record the marker when the install fails", () => {
+        expect(() => ensureDependencies("/py", requirements, { exec: () => ({ status: 1 }) })).toThrow();
+        expect(existsSync(getDepsMarkerPath())).toBe(false);
+    });
+    it("rejects a missing requirements file", () => {
+        expect(() => ensureDependencies("/py", join(tempDir, "nope.txt"))).toThrow(/requirements.txt not found/);
+    });
+    it("records the hash of the requirements it actually installed", () => {
+        ensureDependencies("/py", requirements, { exec: () => ({ status: 0 }) });
+        const marker = readFileSync(getDepsMarkerPath(), "utf-8").trim();
+        expect(marker).toMatch(/^[0-9a-f]{64}$/);
+    });
+});

package/dist/desktop-server/setup-python.test.d.ts

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

package/dist/desktop-server/setup-python.test.js

@@ -0,0 +1,272 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { getPythonDir, getPythonMarkerPath } from "../commands/device/paths.js";
+import { installedPythonTag, installPythonArchive, pythonArchiveName } from "./setup.js";
+let tempDir;
+const savedEnv = {};
+/** Build a tar.gz shaped like python-build-standalone's install_only archive. */
+function writeFakeArchive(dest, layoutDir = "python") {
+    const src = mkdtempSync(join(tmpdir(), "aximo-fake-py-"));
+    try {
+        const root = join(src, layoutDir);
+        mkdirSync(join(root, "bin"), { recursive: true });
+        writeFileSync(join(root, "bin", "python3"), "#!/bin/sh\n");
+        writeFileSync(join(root, "python.exe"), "MZ");
+        execFileSync("tar", ["-czf", dest, "-C", src, layoutDir]);
+    }
+    finally {
+        rmSync(src, { recursive: true, force: true });
+    }
+}
+beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "aximo-setup-py-"));
+    for (const key of ["AXIMO_HOME", "AXIMO_OFFLINE_DIR"]) {
+        savedEnv[key] = process.env[key];
+        delete process.env[key];
+    }
+    process.env["AXIMO_HOME"] = tempDir;
+});
+afterEach(() => {
+    for (const [key, value] of Object.entries(savedEnv)) {
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+    rmSync(tempDir, { recursive: true, force: true });
+});
+describe("pythonArchiveName", () => {
+    it("matches the filename python-build-standalone publishes", () => {
+        const name = pythonArchiveName({
+            target: "x86_64-pc-windows-msvc",
+            sha256: "irrelevant",
+        });
+        expect(name).toBe("cpython-3.12.13+20260414-x86_64-pc-windows-msvc-install_only.tar.gz");
+    });
+});
+describe("installPythonArchive", () => {
+    it("installs from a local archive and stamps the version marker", () => {
+        const archive = join(tempDir, "python.tar.gz");
+        writeFakeArchive(archive);
+        installPythonArchive(archive, { keepArchive: true });
+        expect(existsSync(join(getPythonDir(), "bin", "python3"))).toBe(true);
+        expect(readFileSync(getPythonMarkerPath(), "utf-8")).toBe(installedPythonTag());
+    });
+    it("keeps a staged archive in place so a shared payload survives setup", () => {
+        const archive = join(tempDir, "python.tar.gz");
+        writeFakeArchive(archive);
+        installPythonArchive(archive, { keepArchive: true });
+        expect(existsSync(archive)).toBe(true);
+    });
+    it("removes an archive it downloaded itself", () => {
+        const archive = join(tempDir, "python.tar.gz");
+        writeFakeArchive(archive);
+        installPythonArchive(archive, { keepArchive: false });
+        expect(existsSync(archive)).toBe(false);
+    });
+    it("replaces an existing interpreter rather than merging into it", () => {
+        const stalePath = join(getPythonDir(), "stale-file");
+        mkdirSync(getPythonDir(), { recursive: true });
+        writeFileSync(stalePath, "old");
+        const archive = join(tempDir, "python.tar.gz");
+        writeFakeArchive(archive);
+        installPythonArchive(archive, { keepArchive: true });
+        expect(existsSync(stalePath)).toBe(false);
+        expect(existsSync(join(getPythonDir(), "bin", "python3"))).toBe(true);
+    });
+    it("rejects an archive whose layout is not a python/ root", () => {
+        const archive = join(tempDir, "python.tar.gz");
+        writeFakeArchive(archive, "cpython-3.12.13");
+        expect(() => installPythonArchive(archive, { keepArchive: true })).toThrow(/Unexpected archive layout/);
+    });
+});
+describe("acquirePythonTarball fallback diagnostics", () => {
+    // Found by local air-gap testing: when the server offers no interpreter the CLI
+    // falls back to GitHub, and on an air-gapped network that produced a bare
+    // "fetch failed" with no hint that the missing server payload was the cause.
+    it("explains a failed GitHub fallback instead of surfacing a bare network error", async () => {
+        const script = 'print("x")\n';
+        const requirements = "mss>=10.0\n";
+        const sha = (v) => createHash("sha256").update(v).digest("hex");
+        const manifest = {
+            manifestVersion: 3,
+            version: "abcd1234",
+            script: { sha256: sha(script), size: Buffer.byteLength(script) },
+            requirements: { sha256: sha(requirements), size: Buffer.byteLength(requirements) },
+            // Deliberately no python/wheels: this is a server without the CLI bundle.
+        };
+        const fetchImpl = ((input) => {
+            const url = String(input);
+            if (url.endsWith("/manifest")) {
+                return Promise.resolve(new Response(JSON.stringify(manifest), {
+                    status: 200,
+                    headers: { "Content-Type": "application/json" },
+                }));
+            }
+            if (url.endsWith("remote.py"))
+                return Promise.resolve(new Response(script, { status: 200 }));
+            if (url.endsWith("requirements.txt")) {
+                return Promise.resolve(new Response(requirements, { status: 200 }));
+            }
+            return Promise.reject(new Error("unexpected request"));
+        });
+        // The GitHub download uses global fetch; make the air gap real.
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = (() => Promise.reject(new Error("fetch failed")));
+        try {
+            const { ensurePythonReady } = await import("./setup.js");
+            await expect(ensurePythonReady({ baseUrl: "https://aximo.test", apiKey: "k", fetchImpl })).rejects.toThrow(/offered no embedded Python/);
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+        }
+    });
+    // The same GitHub path is the normal one for cloud, where a transient failure
+    // has nothing to do with on-prem bundles. Telling a cloud user their server
+    // needs a CLI bundle would be actively misleading.
+    it("stays quiet about on-prem bundles when pointed at cloud", async () => {
+        const script = 'print("x")\n';
+        const requirements = "mss>=10.0\n";
+        const sha = (v) => createHash("sha256").update(v).digest("hex");
+        const manifest = {
+            manifestVersion: 2,
+            version: "abcd1234",
+            script: { sha256: sha(script), size: Buffer.byteLength(script) },
+            requirements: { sha256: sha(requirements), size: Buffer.byteLength(requirements) },
+        };
+        const fetchImpl = ((input) => {
+            const url = String(input);
+            if (url.endsWith("/manifest")) {
+                return Promise.resolve(new Response(JSON.stringify(manifest), {
+                    status: 200,
+                    headers: { "Content-Type": "application/json" },
+                }));
+            }
+            if (url.endsWith("remote.py"))
+                return Promise.resolve(new Response(script, { status: 200 }));
+            if (url.endsWith("requirements.txt")) {
+                return Promise.resolve(new Response(requirements, { status: 200 }));
+            }
+            return Promise.reject(new Error("unexpected request"));
+        });
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = (() => Promise.reject(new Error("fetch failed")));
+        try {
+            const { ensurePythonReady } = await import("./setup.js");
+            const { DEFAULT_BASE_URL } = await import("../client.js");
+            await expect(ensurePythonReady({ baseUrl: DEFAULT_BASE_URL, apiKey: "k", fetchImpl })).rejects.toThrow(/^fetch failed$/);
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+        }
+    });
+});
+describe("interpreter source precedence", () => {
+    // README and ADR-003 both promise staged -> server -> GitHub. Each source was
+    // tested alone; the ordering between them was not.
+    const ARCHIVE = pythonArchiveName();
+    const BODY = "staged-archive-bytes";
+    function manifestOffering(archive) {
+        const sha = (v) => createHash("sha256").update(v).digest("hex");
+        const script = 'print("x")\n';
+        const requirements = "mss>=10.0\n";
+        return {
+            manifest: {
+                manifestVersion: 2,
+                version: "abcd1234",
+                script: { sha256: sha(script), size: Buffer.byteLength(script) },
+                requirements: { sha256: sha(requirements), size: Buffer.byteLength(requirements) },
+                python: {
+                    [`${process.platform}-${process.arch}`]: {
+                        archive,
+                        path: `python/x/${archive}`,
+                        sha256: sha("server-bytes"),
+                        size: Buffer.byteLength("server-bytes"),
+                    },
+                },
+            },
+            script,
+            requirements,
+        };
+    }
+    it("prefers a staged archive over the server's", async () => {
+        const staged = join(tempDir, "staged");
+        mkdirSync(staged, { recursive: true });
+        writeFileSync(join(staged, ARCHIVE), BODY);
+        process.env["AXIMO_OFFLINE_DIR"] = staged;
+        const { manifest, script, requirements } = manifestOffering(ARCHIVE);
+        let serverAssetRequested = false;
+        const fetchImpl = ((input) => {
+            const url = String(input);
+            if (url.endsWith("/manifest")) {
+                return Promise.resolve(new Response(JSON.stringify(manifest), {
+                    status: 200,
+                    headers: { "Content-Type": "application/json" },
+                }));
+            }
+            if (url.endsWith("remote.py"))
+                return Promise.resolve(new Response(script, { status: 200 }));
+            if (url.endsWith("requirements.txt")) {
+                return Promise.resolve(new Response(requirements, { status: 200 }));
+            }
+            if (url.includes("/bundle/python/"))
+                serverAssetRequested = true;
+            return Promise.reject(new Error("unexpected request"));
+        });
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = (() => Promise.reject(new Error("github must not be reached")));
+        try {
+            const { ensurePythonReady } = await import("./setup.js");
+            // Fails on the staged archive's checksum, which proves it got that far with
+            // the staged file — and never asked the server or GitHub for one.
+            await expect(ensurePythonReady({ baseUrl: "https://aximo.test", apiKey: "k", fetchImpl })).rejects.toThrow(new RegExp(staged.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+            expect(serverAssetRequested).toBe(false);
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+            delete process.env["AXIMO_OFFLINE_DIR"];
+        }
+    });
+    it("prefers the server over GitHub when it offers a matching archive", async () => {
+        const { manifest, script, requirements } = manifestOffering(ARCHIVE);
+        let serverAssetRequested = false;
+        const fetchImpl = ((input) => {
+            const url = String(input);
+            if (url.endsWith("/manifest")) {
+                return Promise.resolve(new Response(JSON.stringify(manifest), {
+                    status: 200,
+                    headers: { "Content-Type": "application/json" },
+                }));
+            }
+            if (url.endsWith("remote.py"))
+                return Promise.resolve(new Response(script, { status: 200 }));
+            if (url.endsWith("requirements.txt")) {
+                return Promise.resolve(new Response(requirements, { status: 200 }));
+            }
+            if (url.includes("/bundle/python/")) {
+                serverAssetRequested = true;
+                return Promise.resolve(new Response("server-bytes", { status: 200 }));
+            }
+            return Promise.reject(new Error("unexpected request"));
+        });
+        const originalFetch = globalThis.fetch;
+        let githubReached = false;
+        globalThis.fetch = (() => {
+            githubReached = true;
+            return Promise.reject(new Error("fetch failed"));
+        });
+        try {
+            const { ensurePythonReady } = await import("./setup.js");
+            await expect(ensurePythonReady({ baseUrl: "https://aximo.test", apiKey: "k", fetchImpl })).rejects.toThrow(/SHA256 mismatch/);
+            expect(serverAssetRequested).toBe(true);
+            expect(githubReached).toBe(false);
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+        }
+    });
+});

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

@@ -1,8 +1,33 @@
 import { type ChildProcess } from "node:child_process";
-import type { ClientDeps } from "../client.js";
+import { type ClientDeps } from "../client.js";
 export declare const PYTHON_RELEASE = "20260414";
 export declare const PYTHON_VERSION = "3.12.13";
+interface PythonBuild {
+    target: string;
+    sha256: string;
+}
+/** Filename python-build-standalone publishes for this build, also used on disk. */
+export declare function pythonArchiveName(build?: PythonBuild): string;
 export declare function installedPythonTag(): string;
+/**
+ * Extract an already-verified Python archive into place and stamp the markers.
+ *
+ * Callers are responsible for integrity: by the time an archive reaches here it
+ * must have been checked against the expected SHA256.
+ */
+export declare function installPythonArchive(tarball: string, { keepArchive }: {
+    keepArchive: boolean;
+}): void;
+/** pip argv for the agent's requirements, resolving from wheelsDir when given. */
+export declare function pipInstallArgs(requirementsPath: string, wheelsDir?: string): string[];
+export interface DependencyOptions {
+    /** Local wheel directory to resolve from instead of PyPI; undefined means online. */
+    wheelsDir?: string | undefined;
+    exec?: (file: string, args: string[]) => {
+        status: number | null;
+    };
+}
+export declare function ensureDependencies(python: string, requirementsPath: string, options?: DependencyOptions): void;
 export interface PythonReadyResult {
     pythonPath: string;
     scriptPath: string;

package/dist/desktop-server/setup.js

@@ -1,12 +1,15 @@
 import { spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
-import { arch as osArch, platform } from "node:os";
 import { join } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
+import { DEFAULT_BASE_URL, getBaseUrl } from "../client.js";
 import { getAgentCaBundlePath, getAximoDir, getCacheDir, getDepsMarkerPath, getEmbeddedPythonBinary, getPythonDir, getPythonMarkerPath, getRemoteLogPath, } from "../commands/device/paths.js";
 import { ensureAgent } from "./agent-sync.js";
+import { warnIfCliOutdated } from "./cli-version.js";
+import { findOfflinePythonArchive, findOfflineWheelsDir } from "./offline.js";
+import { downloadServerPython, ensureServerWheels, platformKey, resolveServerPython, } from "./bundle-sync.js";
 export const PYTHON_RELEASE = "20260414";
 export const PYTHON_VERSION = "3.12.13";
 const BUILDS = {
@@ -36,16 +39,19 @@ const BUILDS = {
     },
 };
 function selectBuild() {
-    const key = `${platform()}-${osArch()}`;
+    const key = platformKey();
     const build = BUILDS[key];
     if (!build) {
         throw new Error(`Unsupported platform/arch: ${key}`);
     }
     return build;
 }
+/** Filename python-build-standalone publishes for this build, also used on disk. */
+export function pythonArchiveName(build = selectBuild()) {
+    return `cpython-${PYTHON_VERSION}+${PYTHON_RELEASE}-${build.target}-install_only.tar.gz`;
+}
 function buildDownloadUrl(build) {
-    const filename = `cpython-${PYTHON_VERSION}+${PYTHON_RELEASE}-${build.target}-install_only.tar.gz`;
-    return `https://github.com/astral-sh/python-build-standalone/releases/download/${PYTHON_RELEASE}/${filename}`;
+    return `https://github.com/astral-sh/python-build-standalone/releases/download/${PYTHON_RELEASE}/${pythonArchiveName(build)}`;
 }
 export function installedPythonTag() {
     return `${PYTHON_RELEASE}-${PYTHON_VERSION}`;
@@ -92,23 +98,93 @@ function extractTarball(tarball, destDir) {
         throw new Error(`tar extraction failed (exit ${result.status})`);
     }
 }
-async function installEmbeddedPython() {
+/**
+ * Resolve a verified Python archive from the nearest available source.
+ *
+ * Order is staged on disk, then the Aximo server, then GitHub. Every branch
+ * checks the same compiled-in SHA256, so nothing gets a weaker guarantee for
+ * being local — and because that constant ships with the CLI, a mismatched
+ * archive from any source is caught.
+ */
+async function acquirePythonTarball(build, manifest, deps) {
+    const archiveName = pythonArchiveName(build);
+    const staged = findOfflinePythonArchive(archiveName);
+    if (staged) {
+        console.log(`Using staged embedded Python ${PYTHON_VERSION} (${build.target})...`);
+        // Never delete a staged archive — it belongs to the user, not the cache.
+        verifyArchive(staged, build.sha256, { removeOnMismatch: false });
+        return { path: staged, ephemeral: false };
+    }
+    const served = manifest && resolveServerPython(manifest, archiveName);
+    if (served) {
+        const path = await downloadServerPython(served, deps ?? {});
+        verifyArchive(path, build.sha256, { removeOnMismatch: true });
+        // Kept in the cache: re-running setup on the same machine then costs nothing,
+        // which matters most on the slow internal links these servers often sit on.
+        return { path, ephemeral: false };
+    }
+    const path = join(getCacheDir(), `python-${installedPythonTag()}.tar.gz`);
+    console.log(`Fetching embedded Python ${PYTHON_VERSION} (${build.target})...`);
+    try {
+        await downloadTarball(buildDownloadUrl(build), path, build.sha256);
+    }
+    catch (err) {
+        throw new Error(`${err instanceof Error ? err.message : String(err)}${fallbackHint(deps)}`);
+    }
+    return { path, ephemeral: true };
+}
+/**
+ * Extra context for a failed GitHub download, when it would actually help.
+ *
+ * Reaching GitHub means the server offered nothing for this platform. Air-gapped
+ * that can never succeed, and the bare network error gives no hint that a missing
+ * server-side bundle is the cause. But this same path is the normal one for cloud,
+ * where a transient GitHub failure has nothing to do with on-prem bundles — so
+ * only mention them when the CLI is pointed somewhere other than cloud.
+ */
+function fallbackHint(deps) {
+    const baseUrl = deps?.baseUrl ?? getBaseUrl();
+    if (baseUrl === DEFAULT_BASE_URL)
+        return "";
+    return (`\n  The Aximo server at ${baseUrl} offered no embedded Python for ${platformKey()}, ` +
+        "so this fell back to downloading from GitHub.\n" +
+        "  If this machine has no internet access, that server needs the CLI bundle from its " +
+        "on-prem release, or stage the archive locally and set AXIMO_OFFLINE_DIR.");
+}
+/**
+ * Check an archive against the CLI's own compiled-in checksum.
+ *
+ * `removeOnMismatch` matters for recovery, not tidiness: a cached download still
+ * matches the manifest that produced it, so leaving a rejected file in place makes
+ * every later run fail identically until someone clears the cache by hand. A
+ * staged archive belongs to the user, so that one is never removed.
+ */
+function verifyArchive(path, expectedSha256, { removeOnMismatch }) {
+    const actual = hashFile(path);
+    if (actual === expectedSha256)
+        return;
+    if (removeOnMismatch)
+        rmSync(path, { force: true });
+    throw new Error(`SHA256 mismatch for ${path}\n  expected ${expectedSha256}\n  actual ${actual}\n` +
+        "  This CLI and the interpreter it was given do not match. Install the aximo-cli " +
+        "that ships with your current Aximo release.");
+}
+/**
+ * Extract an already-verified Python archive into place and stamp the markers.
+ *
+ * Callers are responsible for integrity: by the time an archive reaches here it
+ * must have been checked against the expected SHA256.
+ */
+export function installPythonArchive(tarball, { keepArchive }) {
     const pythonDir = getPythonDir();
     const cacheDir = getCacheDir();
-    const pythonMarker = getPythonMarkerPath();
-    const depsMarker = getDepsMarkerPath();
     if (existsSync(pythonDir)) {
         rmSync(pythonDir, { recursive: true, force: true });
     }
-    const build = selectBuild();
-    const url = buildDownloadUrl(build);
     mkdirSync(cacheDir, { recursive: true });
-    const tarball = join(cacheDir, `python-${installedPythonTag()}.tar.gz`);
     const staging = join(cacheDir, "python-staging");
     if (existsSync(staging))
         rmSync(staging, { recursive: true, force: true });
-    console.log(`Fetching embedded Python ${PYTHON_VERSION} (${build.target})...`);
-    await downloadTarball(url, tarball, build.sha256);
     console.log("Extracting...");
     extractTarball(tarball, staging);
     const extracted = join(staging, "python");
@@ -118,25 +194,47 @@ async function installEmbeddedPython() {
     mkdirSync(getAximoDir(), { recursive: true });
     renameSync(extracted, pythonDir);
     rmSync(staging, { recursive: true, force: true });
-    rmSync(tarball, { force: true });
-    writeFileSync(pythonMarker, installedPythonTag(), { mode: 0o644 });
+    // A staged or server-cached archive is kept: it belongs to the user, or paying
+    // the download again on the next run costs more than the disk.
+    if (!keepArchive)
+        rmSync(tarball, { force: true });
+    writeFileSync(getPythonMarkerPath(), installedPythonTag(), { mode: 0o644 });
+    const depsMarker = getDepsMarkerPath();
     if (existsSync(depsMarker))
         rmSync(depsMarker, { force: true });
 }
-async function ensurePython() {
+async function installEmbeddedPython(manifest, deps) {
+    mkdirSync(getCacheDir(), { recursive: true });
+    const source = await acquirePythonTarball(selectBuild(), manifest, deps);
+    installPythonArchive(source.path, { keepArchive: !source.ephemeral });
+}
+async function ensurePython(manifest, deps) {
     const binary = getEmbeddedPythonBinary();
     const markerPath = getPythonMarkerPath();
     const marker = existsSync(markerPath) ? readFileSync(markerPath, "utf-8").trim() : "";
     if (marker === installedPythonTag() && existsSync(binary)) {
         return binary;
     }
-    await installEmbeddedPython();
+    await installEmbeddedPython(manifest, deps);
     return binary;
 }
 function hashFile(path) {
     return createHash("sha256").update(readFileSync(path)).digest("hex");
 }
-function ensureDependencies(python, requirementsPath) {
+/** pip argv for the agent's requirements, resolving from wheelsDir when given. */
+export function pipInstallArgs(requirementsPath, wheelsDir) {
+    const args = ["-m", "pip", "install", "--disable-pip-version-check", "--no-warn-script-location"];
+    // --no-index is what makes this airtight: pip must not reach PyPI even for a
+    // single unsatisfied transitive dependency.
+    if (wheelsDir)
+        args.push("--no-index", "--find-links", wheelsDir);
+    args.push("-r", requirementsPath);
+    return args;
+}
+function runPip(file, args) {
+    return spawnSync(file, args, { stdio: "inherit" });
+}
+export function ensureDependencies(python, requirementsPath, options = {}) {
     if (!existsSync(requirementsPath)) {
         throw new Error(`requirements.txt not found at ${requirementsPath}`);
     }
@@ -145,28 +243,37 @@ function ensureDependencies(python, requirementsPath) {
     const marker = existsSync(depsMarker) ? readFileSync(depsMarker, "utf-8").trim() : "";
     if (marker === requirementsHash)
         return;
-    console.log("Installing Python dependencies...");
-    const result = spawnSync(python, [
-        "-m",
-        "pip",
-        "install",
-        "--disable-pip-version-check",
-        "--no-warn-script-location",
-        "-r",
-        requirementsPath,
-    ], { stdio: "inherit" });
+    const { wheelsDir, exec = runPip } = options;
+    console.log(wheelsDir
+        ? `Installing Python dependencies from ${wheelsDir}...`
+        : "Installing Python dependencies...");
+    const result = exec(python, pipInstallArgs(requirementsPath, wheelsDir));
     if (result.status !== 0) {
+        if (wheelsDir) {
+            // Offline, so the usual causes (network, index) don't apply — an
+            // incomplete wheel set almost always means the bundle predates the
+            // requirements the server is now serving.
+            throw new Error(`pip install failed (exit ${result.status}). The wheels in ${wheelsDir} do not satisfy ` +
+                `${requirementsPath}. This usually means the CLI bundle is older than the requirements ` +
+                "your Aximo server is serving — install the CLI bundle from your current on-prem release.");
+        }
         throw new Error(`pip install failed (exit ${result.status})`);
     }
     writeFileSync(depsMarker, requirementsHash, { mode: 0o644 });
 }
 export async function ensurePythonReady(deps) {
-    const pythonPath = await ensurePython();
+    // The agent manifest comes first: it is what tells us whether the server can
+    // supply the interpreter and wheels, which decides where Python comes from.
     const agent = await ensureAgent(deps);
     if (agent.changed) {
         console.log(`Agent script updated to version ${agent.version}`);
     }
-    ensureDependencies(pythonPath, agent.requirementsPath);
+    warnIfCliOutdated(agent.manifest);
+    const pythonPath = await ensurePython(agent.manifest, deps);
+    // Staged files win over the server so a machine that cannot reach it at
+    // all — or is being prepared ahead of time — still works.
+    const wheelsDir = findOfflineWheelsDir() ?? (await ensureServerWheels(agent.manifest, deps));
+    ensureDependencies(pythonPath, agent.requirementsPath, { wheelsDir });
     return {
         pythonPath,
         scriptPath: agent.scriptPath,

package/dist/mobile-control/android-recovery.d.ts

@@ -0,0 +1,5 @@
+import { type ExecFn } from "./exec.js";
+export declare function isWedgedInstrumentationError(err: unknown): boolean;
+export declare const APPIUM_HELPER_PACKAGES: readonly ["io.appium.uiautomator2.server.test", "io.appium.uiautomator2.server", "io.appium.settings"];
+/** Remove stale Appium helper APKs (best-effort) so the driver reinstalls fresh ones. */
+export declare function uninstallAppiumHelpers(serial: string, exec?: ExecFn): Promise<void>;