automify 0.1.9 → 0.1.11

package/README.md

@@ -8,13 +8,15 @@
 
 `Automify` is a Node.js library for AI computer use and command use across web apps, terminals, native desktops, Docker CLI sandboxes, and Docker-backed Linux desktops.
 
+Created by [Aldo Vincenti](https://aldovincenti.com).
+
 Computer use surfaces:
 
-| Surface        | Factory                     | Controlled environment                                      |
-| -------------- | --------------------------- | ----------------------------------------------------------- |
-| Browser        | `automify.browser()`        | Playwright browser with screenshots and actions             |
-| Desktop        | `automify.localComputer()`  | Native desktop on the current macOS, Windows, or Linux host |
-| Docker desktop | `automify.dockerComputer()` | Linux desktop inside a running Docker container             |
+| Surface        | Factory                     | Controlled environment                                    |
+| -------------- | --------------------------- | --------------------------------------------------------- |
+| Browser        | `automify.browser()`        | Playwright browser with screenshots and actions           |
+| Desktop        | `automify.localComputer()`  | Native desktop on macOS, Windows, or Linux X11/Xorg hosts |
+| Docker desktop | `automify.dockerComputer()` | Linux desktop inside a running Docker container           |
 
 Command use surfaces:
 
@@ -40,6 +42,9 @@ Full docs live at [aldovincenti.github.io/automify](https://aldovincenti.github.
 
 ```bash
 npm install automify
+
+# Ubuntu 26.04 only, if Playwright blocks Chromium install
+PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-x64 npm install automify
 ```
 
 Chromium is installed by the package `postinstall` script. Skip it with:
@@ -66,6 +71,37 @@ npm install zod
 
 Automify does not require Zod for `jsonOutput()` or any browser, CLI, or desktop runtime.
 
+### Optional Docker Setup
+
+Docker is required only for `automify.dockerCli()` and `automify.dockerComputer()`.
+
+On macOS and Windows, install Docker Desktop from the official Docker website:
+
+- macOS: <https://docs.docker.com/desktop/setup/install/mac-install/>
+- Windows: <https://docs.docker.com/desktop/setup/install/windows-install/>
+
+On Ubuntu, install Docker from the Ubuntu repositories:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y docker.io
+```
+
+Use `docker.io`, not the `docker` package. In Ubuntu packages, `docker.io` provides the Docker Engine/runtime and CLI.
+
+Start Docker on Ubuntu and enable it after reboot:
+
+```bash
+sudo systemctl enable --now docker
+sudo docker run hello-world
+```
+
+To run Docker commands without `sudo`, add your user to the `docker` group, then log out and back in:
+
+```bash
+sudo usermod -aG docker $USER
+```
+
 ## Quick Start
 
 ```js
@@ -99,7 +135,10 @@ try {
     })
   });
 
-  console.log(run.ok, run.parsed.id, run.parsed.firstName, run.parsed.lastName);
+  console.log(run.parsed.id, run.parsed.firstName, run.parsed.lastName);
+} catch (error) {
+  console.error("Automation failed:", error);
+  process.exitCode = 1;
 } finally {
   await browser.close();
 }
@@ -120,12 +159,12 @@ const browser = await automify.browser({
 });
 
 try {
-  const run = await browser.do("Extract the support email.", {
+  const run = await browser.do("Summarize what you see on the page.", {
     // Optional: structured result shape.
-    output: jsonOutput("support_contact", { email: "string" })
+    output: jsonOutput("page_summary", { title: "string", summary: "string" })
   });
 
-  console.log(run.parsed.email);
+  console.log(run.parsed.title, run.parsed.summary);
 } finally {
   await browser.close();
 }
@@ -147,7 +186,7 @@ const cli = automify.cli({
 await cli.do("Run the tests and summarize failures");
 ```
 
-Use Docker CLI when command execution should happen inside an isolated container. Docker must be installed and running before you create the adapter:
+Use Docker CLI when command execution should happen inside an isolated container. Docker must be installed and running before you create the adapter. See [Optional Docker Setup](#optional-docker-setup) if you still need to install Docker:
 
 ```js
 import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
@@ -198,7 +237,9 @@ try {
 
 ### Desktop Computer Use
 
-Local desktop computer use controls the native desktop on the machine running your Node.js process. It supports macOS, Windows, and Linux through the local desktop adapter. It needs native desktop dependencies that are not installed by default, and your OS may ask for permission to control the desktop.
+Local desktop computer use controls the native desktop on the machine running your Node.js process. It supports macOS, Windows, and Linux through the local desktop adapter. On Linux, local desktop support requires X11/Xorg or Xvfb; Wayland sessions are not supported. It needs native desktop dependencies that are not installed by default, and your OS may ask for permission to control the desktop.
+
+**Linux Wayland is not supported for local desktop control.** If `echo $XDG_SESSION_TYPE` prints `wayland`, `localComputer()` can fail during screenshot capture with native X11 errors such as `BadMatch` / `X_GetImage`. Use an Xorg session, run under Xvfb with `forceVirtualDisplay`, or use `dockerComputer()` for an isolated Linux desktop.
 
 Before running `npx automify-install-desktop`, install the native build tools for your OS:
 
@@ -208,6 +249,9 @@ winget install --id Microsoft.VisualStudio.2022.BuildTools --exact --override "-
 winget install --id Kitware.CMake --exact --source winget
 
 # macOS: Xcode Command Line Tools plus CMake on PATH.
+# If Homebrew is not installed, install it first:
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
 xcode-select --install
 brew install cmake
 
@@ -221,7 +265,9 @@ sudo dnf install -y gcc-c++ make cmake libXtst-devel libpng-devel
 sudo pacman -S --needed base-devel cmake libxtst libpng
 ```
 
-On Linux, install the full package list before running `npx automify-install-desktop`; the installer checks for command-line build tools but does not verify every native library package. On headless Linux hosts, also install `xvfb` unless you manage `DISPLAY` yourself. On macOS and Windows, `cmake --version` must work in the terminal where you run `npx automify-install-desktop`. On Windows, the VS Code CMake Tools extension is not enough by itself, and Visual Studio 2026 is not currently recognized by the native build chain used by nut.js.
+On Linux, install the full package list before running `npx automify-install-desktop`; the installer checks for command-line build tools but does not verify every native library package. Linux local desktop capture is X11-based: use Xorg/X11, not Wayland. On headless Linux hosts, also install `xvfb` unless you manage `DISPLAY` yourself. On macOS, install Homebrew first if `brew` is not available, then install CMake with `brew install cmake`. On macOS and Windows, `cmake --version` must work in the terminal where you run `npx automify-install-desktop`. On Windows, the VS Code CMake Tools extension is not enough by itself, and Visual Studio 2026 is not currently recognized by the native build chain used by nut.js.
+
+`npx automify-install-desktop` stores the compiled desktop runtime outside `node_modules` in a long-term cache, so normal `npm update` runs do not remove it. If the command is run again and the cached runtime already matches the current platform, CPU architecture, Node ABI, and pinned nut.js/libnut revisions, Automify prints a skip message and exits without rebuilding. Use `npx automify-install-desktop --force` (or `npx automify-install-desktop force`) to rebuild a compatible cache anyway. If a later `npm install` or `npm update` detects that a previously installed desktop runtime no longer matches the current environment, Automify rebuilds it automatically during `postinstall`. Default cache roots are `%LOCALAPPDATA%\automify\desktop-runtime` on Windows, `~/Library/Caches/automify/desktop-runtime` on macOS, and `${XDG_CACHE_HOME:-~/.cache}/automify/desktop-runtime` on Linux. Override with `AUTOMIFY_DESKTOP_RUNTIME_DIR`; disable auto-rebuild with `AUTOMIFY_SKIP_DESKTOP_AUTO_REBUILD=1`.
 
 ```js
 import { initAutomify } from "automify";
@@ -239,14 +285,14 @@ const desktop = await automify.localComputer();
 
 try {
   await desktop.do(
-    "Open the Calendar app installed on this computer, find the next event after today, and summarize it. Do not create or edit events."
+    "Open the Calendar app installed on this computer, find the next event, and summarize it. Do not create or edit events."
   );
 } finally {
   await desktop.close();
 }
 ```
 
-For isolated Linux desktop computer use, use Docker. `dockerComputer()` can run from a macOS, Windows, or Linux host with Docker installed and running, but the desktop it controls inside the container is Linux. Docker desktop does not use `automify-install-desktop`; it needs a running Docker daemon and an initial app command:
+For isolated Linux desktop computer use, use Docker. `dockerComputer()` can run from a macOS, Windows, or Linux host with Docker installed and running, but the desktop it controls inside the container is Linux. This is the recommended path when the host Linux session uses Wayland, because `localComputer()` does not support Wayland. Docker desktop does not use `automify-install-desktop`; it needs a running Docker daemon and an initial app command. See [Optional Docker Setup](#optional-docker-setup) if Docker is not installed yet:
 
 ```js
 import { initAutomify } from "automify";

package/examples/browser-basic.js

@@ -24,7 +24,10 @@ try {
       lastName: "string"
     })
   });
-  console.log(result.ok, result.parsed);
+  console.log(result.parsed);
+} catch (error) {
+  console.error("Automation failed:", error);
+  process.exitCode = 1;
 } finally {
   await browser.close();
 }

package/examples/desktop-local.js

@@ -17,7 +17,7 @@ const desktop = automify.computer({
 });
 
 const instruction =
-  "Open the Calendar app installed on this computer, find the next event after today, and summarize it. Do not create or edit events.";
+  "Open the Calendar app installed on this computer, find the next event, and summarize it. Do not create or edit events.";
 
 await desktop.do(instruction, {
   screenshots: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "automify",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "AI computer use for browser, CLI, and desktop in Node.js.",
   "homepage": "https://aldovincenti.github.io/automify",
   "bugs": {
@@ -36,7 +36,7 @@
     "SECURITY.md"
   ],
   "scripts": {
-    "postinstall": "node scripts/install-browser.js",
+    "postinstall": "node scripts/install-browser.js && node scripts/install-desktop-if-needed.js",
     "install:desktop": "node scripts/install-desktop.js",
     "docs:arguments": "node scripts/generate-argument-reference.js",
     "test": "node --test test/*.test.js",

package/scripts/install-browser.js

@@ -9,6 +9,7 @@ if (process.env.AUTOMIFY_SKIP_BROWSER_INSTALL === "1" || process.env.PLAYWRIGHT_
 }
 
 const playwrightCli = join(dirname(require.resolve("playwright")), "cli.js");
+console.log("Automify: installing Playwright browser...");
 const result = spawnSync(process.execPath, [playwrightCli, "install", "chromium"], {
   cwd: process.cwd(),
   stdio: "inherit"

package/scripts/install-desktop-if-needed.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  desktopRuntimeDir,
+  desktopRuntimeIsInstalled,
+  desktopRuntimeKey,
+  findDesktopRuntimeManifests
+} from "../src/lib/desktop-runtime.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+
+if (process.env.AUTOMIFY_SKIP_DESKTOP_INSTALL === "1" || process.env.AUTOMIFY_SKIP_DESKTOP_AUTO_REBUILD === "1") {
+  process.exit(0);
+}
+
+if (desktopRuntimeIsInstalled()) {
+  process.exit(0);
+}
+
+const existingManifests = findDesktopRuntimeManifests();
+const legacyNodeModulesRuntime = existsSync(join(root, "node_modules", "@nut-tree", "nut-js", "package.json"));
+
+if (existingManifests.length === 0 && !legacyNodeModulesRuntime) {
+  process.exit(0);
+}
+
+console.log("Automify desktop runtime was previously installed but is not compatible with this environment.");
+console.log(`Rebuilding desktop runtime cache: ${desktopRuntimeKey()}`);
+console.log(`Runtime directory: ${desktopRuntimeDir()}`);
+
+const result = spawnSync(process.execPath, [join(__dirname, "install-desktop.js")], {
+  cwd: root,
+  env: process.env,
+  stdio: "inherit"
+});
+
+process.exit(result.status ?? 1);

package/scripts/install-desktop.js

@@ -4,6 +4,17 @@ import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } fr
 import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import {
+  DESKTOP_RUNTIME_MANIFEST,
+  desktopRuntimeDir,
+  desktopRuntimeIsInstalled,
+  desktopRuntimeKey,
+  desktopRuntimeManifest,
+  desktopRuntimeNodeModules,
+  desktopRuntimeRefs,
+  resetDesktopRuntimeInstallState
+} from "../src/lib/desktop-runtime.js";
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const root = resolve(__dirname, "..");
 const buildRoot = process.env.AUTOMIFY_DESKTOP_BUILD_DIR
@@ -12,21 +23,32 @@ const buildRoot = process.env.AUTOMIFY_DESKTOP_BUILD_DIR
 const nutSource = join(buildRoot, "nut.js");
 const libnutSource = join(buildRoot, "libnut-core");
 const macPermissionsSource = join(buildRoot, "node-mac-permissions");
-const refs = {
-  nut: process.env.AUTOMIFY_DESKTOP_NUT_REF ?? "e413fa1f19a19c4631812e4e1eaf47aa732b5cbe",
-  libnutCore: process.env.AUTOMIFY_DESKTOP_LIBNUT_CORE_REF ?? "6bbe5825f1123bcd740117ca932c8b1c6cffb48c",
-  macPermissions: process.env.AUTOMIFY_DESKTOP_MAC_PERMISSIONS_REF ?? "6b6ddee993ddce5071b637e42f6ee1434150d0bb"
-};
-const nodeModules = join(root, "node_modules");
+const refs = desktopRuntimeRefs();
+const runtimeDir = desktopRuntimeDir();
+const runtimeNodeModules = desktopRuntimeNodeModules();
+const nodeModules = runtimeNodeModules;
 const nutScope = join(nodeModules, "@nut-tree");
 const platformPackageName = `@nut-tree/libnut-${process.platform}`;
 const platformPackageDir = join(nutScope, `libnut-${process.platform}`);
 const macPermissionsPackageDir = join(nutScope, "node-mac-permissions");
+const forceInstall = process.argv.slice(2).some((arg) => arg === "--force" || arg === "force");
 
 const runtimeDependencies = ["jimp@1.6.1", "node-abort-controller@3.1.1", "clipboardy@2.3.0", "bindings@1.5.0"];
 
+if (!forceInstall && desktopRuntimeIsInstalled()) {
+  console.log("Automify desktop runtime is already installed and compatible; skipping rebuild.");
+  console.log(`Runtime directory: ${runtimeDir}`);
+  console.log("Use `npx automify-install-desktop --force` to rebuild it anyway.");
+  process.exit(0);
+}
+
 console.log("Building official nut.js from source.");
+if (forceInstall) {
+  console.log("Force enabled: rebuilding the desktop runtime even if the cache is compatible.");
+}
 console.log(`Build directory: ${buildRoot}`);
+console.log(`Runtime directory: ${runtimeDir}`);
+console.log(`Runtime key: ${desktopRuntimeKey()}`);
 console.log(`nut.js ref: ${refs.nut}`);
 console.log(`libnut-core ref: ${refs.libnutCore}`);
 if (process.platform === "darwin") {
@@ -36,6 +58,9 @@ if (process.platform === "darwin") {
 checkBuildPrerequisites();
 
 mkdirSync(buildRoot, { recursive: true });
+mkdirSync(runtimeDir, { recursive: true });
+resetDesktopRuntimeInstallState();
+writeRuntimePackageJson();
 cloneOrPull("https://github.com/nut-tree/libnut-core.git", libnutSource, refs.libnutCore);
 cloneOrPull("https://github.com/nut-tree/nut.js.git", nutSource, refs.nut);
 if (process.platform === "darwin") {
@@ -69,7 +94,7 @@ writeLibnutImportBridge();
 runPnpm(["--filter", "@nut-tree/nut-js", "run", "compile"], { cwd: nutSource });
 patchNutJimpCompatibility();
 
-run("npm", ["install", "--no-save", ...runtimeDependencies], { cwd: root });
+run("npm", ["install", "--no-save", ...runtimeDependencies], { cwd: runtimeDir });
 
 installWorkspacePackage(join(nutSource, "core", "shared"), join(nutScope, "shared"));
 installWorkspacePackage(join(nutSource, "core", "provider-interfaces"), join(nutScope, "provider-interfaces"));
@@ -81,9 +106,20 @@ if (process.platform === "darwin") {
   installWorkspacePackage(macPermissionsSource, macPermissionsPackageDir);
 }
 
-run("node", ["-e", "import('@nut-tree/nut-js').then(() => console.log('nut.js source build import ok'))"], {
-  cwd: root
-});
+writeRuntimeManifest();
+run(
+  "node",
+  [
+    "-e",
+    `const { createRequire } = require("node:module");
+const { join } = require("node:path");
+const runtimeDir = process.argv[1];
+createRequire(join(runtimeDir, "automify-desktop-runtime.cjs"))("@nut-tree/nut-js");
+console.log("nut.js source build import ok");`,
+    runtimeDir
+  ],
+  { cwd: root }
+);
 
 function cloneOrPull(repo, target, ref) {
   if (existsSync(join(target, ".git"))) {
@@ -160,22 +196,26 @@ function resolveCommand(command) {
 function commandCandidates(command) {
   const candidates = [];
 
+  const npmCli = npmCliCandidate(command);
+  if (npmCli) candidates.push(npmCli);
+
   if (process.platform === "win32" && ["npm", "npx"].includes(command)) {
     candidates.push({ command: `${command}.cmd`, args: [] });
   }
 
-  const npmCli = npmCliCandidate(command);
-  if (npmCli) candidates.push(npmCli);
-
   candidates.push({ command, args: [] });
   return candidates;
 }
 
 function npmCliCandidate(command) {
-  if (!["npm", "npx"].includes(command) || !process.env.npm_execpath) return null;
-  if (command === "npm") return { command: process.execPath, args: [process.env.npm_execpath] };
+  if (!["npm", "npx"].includes(command)) return null;
+
+  const npmExecPath =
+    process.env.npm_execpath ?? join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js");
+  if (!existsSync(npmExecPath)) return null;
+  if (command === "npm") return { command: process.execPath, args: [npmExecPath] };
 
-  const npxExecPath = join(dirname(process.env.npm_execpath), "npx-cli.js");
+  const npxExecPath = join(dirname(npmExecPath), "npx-cli.js");
   if (!existsSync(npxExecPath)) return null;
   return { command: process.execPath, args: [npxExecPath] };
 }
@@ -404,6 +444,35 @@ function installWorkspacePackage(source, target) {
   });
 }
 
+function writeRuntimePackageJson() {
+  writeText(
+    join(runtimeDir, "package.json"),
+    `${JSON.stringify(
+      {
+        private: true,
+        name: "automify-desktop-runtime",
+        description: "Persistent native runtime cache for Automify local desktop support."
+      },
+      null,
+      2
+    )}\n`
+  );
+}
+
+function writeRuntimeManifest() {
+  writeText(
+    join(runtimeDir, DESKTOP_RUNTIME_MANIFEST),
+    `${JSON.stringify(
+      {
+        ...desktopRuntimeManifest(),
+        createdAt: new Date().toISOString()
+      },
+      null,
+      2
+    )}\n`
+  );
+}
+
 function run(command, args, options = {}) {
   const result = runResolvedCommand(command, args, {
     cwd: options.cwd ?? root,

package/src/index.d.ts

@@ -211,7 +211,8 @@ export interface LocalDesktopComputerOptions {
   };
   /**
    * Linux only. Defaults to true when DISPLAY is missing. Starts Xvfb so the
-   * local nut.js desktop adapter can run on headless servers.
+   * local nut.js desktop adapter can run on headless servers. Linux local
+   * desktop capture is X11-based; Wayland sessions are not supported.
    */
   virtualDisplay?:
     | boolean
@@ -224,6 +225,11 @@ export interface LocalDesktopComputerOptions {
         args?: string[];
         startupMs?: number;
       };
+  /**
+   * Linux only. Forces Xvfb even when DISPLAY is already set. Ignored on macOS
+   * and Windows. Use this when the host Linux session is Wayland or otherwise
+   * unsuitable for X11 screenshot capture.
+   */
   forceVirtualDisplay?: boolean;
   display?:
     | string

package/src/lib/argument-reference.js

@@ -72,13 +72,13 @@ export const argumentReference = [
     surface: "automify.localComputer()",
     preferred: ["viewport", "mouse", "keyboard", "calibration", "virtualDisplay", "logFile"],
     notes:
-      "Creates a local desktop runner and takes an exclusive cross-process lock until close(). Use logFile to capture automation and local desktop events."
+      "Creates a local desktop runner and takes an exclusive cross-process lock until close(). Linux local desktop requires X11/Xorg or Xvfb; Wayland is not supported. Use logFile to capture automation and local desktop events."
   },
   {
     surface: "createLocalDesktopComputer()",
     preferred: ["viewport", "mouse", "keyboard", "calibration", "virtualDisplay", "logFile"],
     notes:
-      "Grouped mouse, keyboard, and calibration options are preferred over the older flat names. Use logFile to capture local desktop events. Local desktop control takes an exclusive cross-process lock until close()."
+      "Grouped mouse, keyboard, and calibration options are preferred over the older flat names. Linux local desktop requires X11/Xorg or Xvfb; Wayland is not supported. Use logFile to capture local desktop events. Local desktop control takes an exclusive cross-process lock until close()."
   },
   {
     surface: "createDockerDesktopComputer()",

package/src/lib/desktop-runtime.js

@@ -0,0 +1,142 @@
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export const DESKTOP_RUNTIME_PACKAGE = "@nut-tree/nut-js";
+export const DESKTOP_RUNTIME_MANIFEST = "automify-desktop-runtime.json";
+
+export function desktopRuntimeRefs(env = process.env) {
+  return {
+    nut: env.AUTOMIFY_DESKTOP_NUT_REF ?? "e413fa1f19a19c4631812e4e1eaf47aa732b5cbe",
+    libnutCore: env.AUTOMIFY_DESKTOP_LIBNUT_CORE_REF ?? "6bbe5825f1123bcd740117ca932c8b1c6cffb48c",
+    macPermissions: env.AUTOMIFY_DESKTOP_MAC_PERMISSIONS_REF ?? "6b6ddee993ddce5071b637e42f6ee1434150d0bb"
+  };
+}
+
+export function desktopRuntimeCompatibility(env = process.env) {
+  const refs = desktopRuntimeRefs(env);
+  return {
+    platform: process.platform,
+    arch: process.arch,
+    nodeAbi: process.versions.modules,
+    nutRef: refs.nut,
+    libnutCoreRef: refs.libnutCore,
+    macPermissionsRef: process.platform === "darwin" ? refs.macPermissions : undefined
+  };
+}
+
+export function desktopRuntimeKey(compatibility = desktopRuntimeCompatibility()) {
+  return [
+    compatibility.platform,
+    compatibility.arch,
+    `node-${compatibility.nodeAbi}`,
+    `nut-${shortRef(compatibility.nutRef)}`,
+    `libnut-${shortRef(compatibility.libnutCoreRef)}`,
+    compatibility.macPermissionsRef ? `macperms-${shortRef(compatibility.macPermissionsRef)}` : null
+  ]
+    .filter(Boolean)
+    .join("-");
+}
+
+export function defaultDesktopRuntimeRoot(env = process.env) {
+  if (env.AUTOMIFY_DESKTOP_RUNTIME_DIR) {
+    return resolve(env.AUTOMIFY_DESKTOP_RUNTIME_DIR);
+  }
+
+  if (process.platform === "win32") {
+    return join(env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "automify", "desktop-runtime");
+  }
+
+  if (process.platform === "darwin") {
+    return join(homedir(), "Library", "Caches", "automify", "desktop-runtime");
+  }
+
+  return join(env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "automify", "desktop-runtime");
+}
+
+export function desktopRuntimeDir(env = process.env) {
+  return join(defaultDesktopRuntimeRoot(env), desktopRuntimeKey(desktopRuntimeCompatibility(env)));
+}
+
+export function desktopRuntimeNodeModules(env = process.env) {
+  return join(desktopRuntimeDir(env), "node_modules");
+}
+
+export function desktopRuntimePackageJsonPath(env = process.env) {
+  return join(desktopRuntimeNodeModules(env), "@nut-tree", "nut-js", "package.json");
+}
+
+export function desktopRuntimeManifestPath(env = process.env) {
+  return join(desktopRuntimeDir(env), DESKTOP_RUNTIME_MANIFEST);
+}
+
+export function desktopRuntimeManifest(env = process.env) {
+  return {
+    version: 1,
+    package: DESKTOP_RUNTIME_PACKAGE,
+    runtimeDir: desktopRuntimeDir(env),
+    compatibility: desktopRuntimeCompatibility(env)
+  };
+}
+
+export function resetDesktopRuntimeInstallState(env = process.env) {
+  const runtimeDir = desktopRuntimeDir(env);
+  rmSync(join(desktopRuntimeNodeModules(env), "@nut-tree"), { recursive: true, force: true });
+  rmSync(join(runtimeDir, "package-lock.json"), { recursive: true, force: true });
+  rmSync(join(runtimeDir, "npm-shrinkwrap.json"), { recursive: true, force: true });
+}
+
+export function readDesktopRuntimeManifest(env = process.env) {
+  const path = desktopRuntimeManifestPath(env);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+export function findDesktopRuntimeManifests(env = process.env) {
+  const root = defaultDesktopRuntimeRoot(env);
+  if (!existsSync(root)) return [];
+
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const runtimeDir = join(root, entry.name);
+      const manifestPath = join(runtimeDir, DESKTOP_RUNTIME_MANIFEST);
+      if (!existsSync(manifestPath)) return null;
+      try {
+        return {
+          runtimeDir,
+          manifestPath,
+          manifest: JSON.parse(readFileSync(manifestPath, "utf8"))
+        };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+export function desktopRuntimeIsInstalled(env = process.env) {
+  const manifest = readDesktopRuntimeManifest(env);
+  return desktopRuntimeManifestMatches(manifest, env) && existsSync(desktopRuntimePackageJsonPath(env));
+}
+
+export function desktopRuntimeManifestMatches(manifest, env = process.env) {
+  if (!manifest || manifest.version !== 1 || manifest.package !== DESKTOP_RUNTIME_PACKAGE) return false;
+
+  const expected = desktopRuntimeCompatibility(env);
+  const actual = manifest.compatibility ?? {};
+  return (
+    actual.platform === expected.platform &&
+    actual.arch === expected.arch &&
+    actual.nodeAbi === expected.nodeAbi &&
+    actual.nutRef === expected.nutRef &&
+    actual.libnutCoreRef === expected.libnutCoreRef &&
+    actual.macPermissionsRef === expected.macPermissionsRef
+  );
+}
+
+function shortRef(ref) {
+  return String(ref ?? "unknown")
+    .replace(/[^a-zA-Z0-9._-]/g, "_")
+    .slice(0, 12);
+}

package/src/lib/local-desktop-computer.js

@@ -1,3 +1,5 @@
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
 import { readFile, unlink } from "node:fs/promises";
 import { execFile, spawn } from "node:child_process";
 import { tmpdir } from "node:os";
@@ -8,6 +10,12 @@ import { promisify } from "node:util";
 import { AutomifyError } from "./errors.js";
 import { acquireAdapterLock } from "./adapter-locks.js";
 import { assertKnownOptions, normalizeLogFile, writeDebugLogFile } from "./runtime.js";
+import {
+  DESKTOP_RUNTIME_PACKAGE,
+  desktopRuntimeDir,
+  desktopRuntimeManifestMatches,
+  desktopRuntimeManifestPath
+} from "./desktop-runtime.js";
 
 const execFileAsync = promisify(execFile);
 const LOCAL_DESKTOP_OPTION_KEYS = new Set([
@@ -128,6 +136,7 @@ const DEFAULT_DESKTOP_INSTRUCTIONS = [
   "You are controlling a native desktop through screenshots and mouse/keyboard actions.",
   "Orient from the screenshot first: identify the active app, visible window, focused field, current page, and the specific target required by the task before acting.",
   "Use deterministic entry points. For a website or web app, use the browser address bar only when a browser is clearly focused; otherwise open the browser through a visible Dock/app icon or OS search/launcher, then use the address bar. For app content, use visible in-app search, filters, or navigation controls.",
+  "Before using a terminal to run a shell command, confirm the terminal is idle and showing a prompt. If the visible terminal is occupied by a running foreground process, such as the Node.js script that started this session, do not type commands into it; use the OS launcher/Dock/search or a separate idle terminal session instead.",
   "Do not open or use Command+Tab, Alt+Tab, Mission Control, or other cyclic app/window switchers unless the task explicitly asks to switch to the previous app. Cyclic switching is unreliable because the open-app order is unknown.",
   "Do not click as a probe. Click only when the screenshot shows a specific visible target and the purpose of that click is clear from the task or current UI. Prefer named controls, fields, menu items, visible app icons, and address/search fields over unlabeled areas.",
   "If the target is not visible, choose a deterministic recovery path: direct URL, OS search/launcher, in-app search, visible navigation, or a screenshot/wait when loading is visible. Do not repeat nearly identical clicks after no visible change.",
@@ -448,16 +457,39 @@ async function saveNutImageObject(nut, image, options = {}) {
 }
 
 async function importNut() {
+  let runtimeError;
   try {
-    return await import("@nut-tree/nut-js");
+    const runtimeNut = importNutFromDesktopRuntime();
+    if (runtimeNut) return runtimeNut;
   } catch (error) {
+    runtimeError = error;
+  }
+
+  try {
+    return await import(DESKTOP_RUNTIME_PACKAGE);
+  } catch (error) {
+    const runtimeSuffix = runtimeError ? ` Cached desktop runtime import failed: ${runtimeError.message}` : "";
     throw new AutomifyError(
-      `createLocalDesktopComputer requires the local desktop adapter dependency built from source. ${localDesktopInstallHelp()} After the OS prerequisites are available, run: npx automify-install-desktop`,
+      `createLocalDesktopComputer requires the local desktop adapter dependency built from source. ${localDesktopInstallHelp()} After the OS prerequisites are available, run: npx automify-install-desktop.${runtimeSuffix}`,
       { cause: error }
     );
   }
 }
 
+function importNutFromDesktopRuntime() {
+  const manifestPath = desktopRuntimeManifestPath();
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!desktopRuntimeManifestMatches(manifest)) return null;
+
+  const runtimeRequire = createRequire(join(desktopRuntimeDir(), "automify-desktop-runtime.cjs"));
+  return runtimeRequire(DESKTOP_RUNTIME_PACKAGE);
+}
+
 function normalizeLocalDesktopEnvironment(environment) {
   if (environment == null) return undefined;
   if (typeof environment !== "string" || environment.trim() === "") {