automify 0.2.0 → 0.3.1

package/README.md

@@ -6,33 +6,35 @@
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20.12.2-brightgreen.svg)](https://nodejs.org/)
 
-`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).
+`Automify` is a Node.js library for AI computer use and command use across web apps, terminals, native desktops, Docker sandboxes, and QEMU-backed virtual machines.
 
 Computer use surfaces:
 
-| 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           |
+| 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           |
+| Virtual desktop | `automify.virtualComputer()` | Linux desktop inside a QEMU VM                            |
 
 Command use surfaces:
 
-| Surface    | Factory                | What it does                                          |
-| ---------- | ---------------------- | ----------------------------------------------------- |
-| CLI        | `automify.cli()`       | Terminal automation through model-requested commands  |
-| Docker CLI | `automify.dockerCli()` | Containerized terminal automation with running Docker |
+| Surface     | Factory                 | What it does                                          |
+| ----------- | ----------------------- | ----------------------------------------------------- |
+| CLI         | `automify.cli()`        | Terminal automation through model-requested commands  |
+| Docker CLI  | `automify.dockerCli()`  | Containerized terminal automation with running Docker |
+| Virtual CLI | `automify.virtualCli()` | Terminal automation inside a QEMU VM                  |
 
 OpenAI and Anthropic models are supported, and any other model can be plugged in with a custom provider adapter.
 
 ## What You Get
 
-- Computer use for browser, local desktop, Docker desktop, and custom computer adapters.
-- Command use for local CLI and Docker CLI runs.
+- Computer use for browser, local desktop, Docker desktop, QEMU virtual desktop, and custom computer adapters.
+- Command use for local CLI, Docker CLI, and QEMU virtual CLI runs.
 - One `.do()` loop: give the model a task, let it request actions, return a structured result.
+- Step-by-step task builders for longer workflows that should read like a checklist.
 - Structured task input with `data` and structured output with `jsonOutput()`.
+- Screen recording for browser and desktop-style computer runs.
 - Built-in OpenAI and Anthropic support, plus custom model adapters.
 - Practical guardrails: domain allowlists, command policies, screenshot controls, max steps, and hooks.
 
@@ -102,6 +104,45 @@ To run Docker commands without `sudo`, add your user to the `docker` group, then
 sudo usermod -aG docker $USER
 ```
 
+### Optional QEMU Setup
+
+QEMU is required only for `automify.virtualCli()`, `automify.virtualComputer()`, and `createVirtualDesktopComputer()`.
+When no image is configured, Automify downloads the official Debian genericcloud qcow2 image into a local cache, then prepares a reusable Automify-ready Debian qcow2 with the `automify` SSH user already provisioned. Runtime VMs boot from short-lived overlays backed by that prepared image. Pass `image` or `vm.image` only when you want to use your own bootable Linux disk image with SSH access.
+
+```bash
+# Ubuntu
+sudo apt-get install -y qemu-system qemu-utils
+
+# macOS
+brew install qemu
+
+# Windows
+# Install QEMU from https://www.qemu.org/download/
+```
+
+Pre-warm or refresh QEMU image caches:
+
+```bash
+# Pre-warm the minimal QEMU CLI cache.
+npx automify-qemu-image
+
+# Pre-warm a QEMU CLI cache for examples that need Node.js in the VM.
+npx automify-qemu-image --package coreutils --package nodejs
+
+# Pre-warm the QEMU desktop cache with Xvfb/openbox/xterm/xdotool/scrot.
+npx automify-qemu-image --desktop
+
+# Re-download the Debian base image and rebuild the prepared cache.
+npx automify-qemu-image --force-download
+
+# Pre-warm an alternate qcow2 URL into its own cache.
+npx automify-qemu-image \
+  --image-url https://example.com/path/linux.qcow2 \
+  --cache-dir ~/.cache/automify/qemu-custom
+```
+
+Use `--image-url` for an alternate apt-based Linux cloud qcow2 that Automify should download, boot, and prepare. Use the same URL and cache directory at runtime with `vm.imageUrl` or `qemuImageUrl` plus `defaultImageCache`. If you pass a local disk with `image` or `vm.image`, Automify uses that qcow2 directly instead of preparing it; the image must already boot, accept SSH, and include the desktop packages required for virtual desktop runs.
+
 ## Quick Start
 
 ```js
@@ -217,7 +258,7 @@ const automify = initAutomify({
 const cli = automify.dockerCli({
   // Optional: choose resource limits without changing the default image.
   container: { cpus: 1, memory: "1g" },
-  // Optional: install Debian packages before commands run.
+  // Optional: install apt packages before commands run.
   additionalAptPackages: ["coreutils", "nodejs"],
   // Optional: mount a host folder into the container workspace.
   shared: { hostPath: sharedDir, containerPath: "/workspace" }
@@ -235,6 +276,38 @@ try {
 }
 ```
 
+Use QEMU virtual CLI when command execution should happen inside a real VM. QEMU must be installed. By default, Automify prepares a minimal Debian cloud image automatically; pass `image` or `vm.image` only to use a custom VM disk:
+
+```js
+const cli = automify.virtualCli({
+  vm: {
+    memory: "2g",
+    cpus: 2
+  },
+  additionalAptPackages: ["coreutils", "nodejs"],
+  shared: { hostPath: process.cwd(), containerPath: "/workspace" }
+});
+
+try {
+  await cli.do("Run 'node --version' and summarize the result");
+} finally {
+  await cli.close();
+}
+```
+
+To reuse an alternate qcow2 URL that you pre-warmed with `automify-qemu-image --image-url`, pass the same URL and cache directory:
+
+```js
+const cli = automify.virtualCli({
+  vm: {
+    imageUrl: "https://example.com/path/linux.qcow2"
+  },
+  defaultImageCache: {
+    dir: "/var/cache/automify-qemu-custom"
+  }
+});
+```
+
 ### 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. 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.
@@ -255,17 +328,11 @@ winget install --id Kitware.CMake --exact --source winget
 xcode-select --install
 brew install cmake
 
-# Debian/Ubuntu Linux.
+# Ubuntu Linux.
 sudo apt-get install -y git build-essential cmake pkg-config libx11-dev libxtst-dev libpng++-dev
-
-# Fedora Linux.
-sudo dnf install -y gcc-c++ make cmake libXtst-devel libpng-devel
-
-# Arch Linux.
-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. 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.
+On Linux, the documented local desktop path is Ubuntu. 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 Ubuntu 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`.
 
@@ -319,7 +386,25 @@ try {
 }
 ```
 
-Local desktop computer use takes an exclusive cross-process lock until `close()`. Docker desktop locks are scoped to the container name, so different containers can run in parallel.
+For a real VM-backed Linux desktop, use QEMU. `virtualComputer()` starts a QEMU VM, connects over SSH, and controls an Xvfb desktop inside the guest with `xdotool` and `scrot`. By default, Automify prepares a minimal Debian cloud image automatically; pass `image` or `vm.image` only to use a custom VM disk:
+
+```js
+const desktop = await automify.virtualComputer({
+  vm: {
+    memory: "2g",
+    cpus: 2
+  },
+  desktop: { startupCommand: "xterm" }
+});
+
+try {
+  await desktop.do("Use the open terminal to run 'uname -a' and summarize the VM system information");
+} finally {
+  await desktop.close();
+}
+```
+
+Local desktop computer use takes an exclusive cross-process lock until `close()`. Docker desktop locks are scoped to the container name, and QEMU virtual desktop locks are scoped to the VM name.
 
 ### Custom Computer Use
 
@@ -335,7 +420,7 @@ await automify.computer({ computer }).do("Use the remote app with the supplied t
 });
 ```
 
-Custom computer adapters can expose `environment`, `displayWidth`, and `displayHeight` when they control a fixed remote target. Built-in local and Docker desktop adapters infer or choose those values for you.
+Custom computer adapters can expose `environment`, `displayWidth`, and `displayHeight` when they control a fixed remote target. Built-in local, Docker desktop, and QEMU virtual desktop adapters infer or choose those values for you.
 
 ## Input And Output
 
@@ -360,12 +445,116 @@ const run = await browser.do("Create the lead from data and return the saved rec
 });
 ```
 
+For longer workflows, build the task as ordered steps and run it at the end. This is useful when the task has
+distinct phases, such as navigate, wait, create, verify, and extract:
+
+```js
+const run = await browser
+  .addStep("Open the contacts page.")
+  .addWait("the contacts table is visible")
+  .addStep("Create the lead from data.")
+  .addExtract("Return the saved record JSON.", {
+    key: "lead",
+    shape: { id: "string", firstName: "string", lastName: "string" }
+  })
+  .addData({ firstName: "Ada", lastName: "Lovelace" })
+  .run();
+
+console.log(run.parsed.lead.id);
+```
+
+You can also start from `browser.task()` when you want to keep a reusable builder variable:
+
+```js
+const task = browser
+  .task({ limits: { steps: 30 } })
+  .addStep("Open the billing page.")
+  .addWait("the invoice list has finished loading")
+  .addObserve("Find the newest unpaid invoice.")
+  .addAssert("Confirm the customer name matches the data.")
+  .addExtract("Return the invoice id and total.", {
+    key: "invoice",
+    shape: { id: "string", total: "number" }
+  })
+  .addExtract("Return audit metadata.", {
+    key: "audit",
+    shape: { requestId: "string" }
+  })
+  .withData({ customerName: "Ada Lovelace" });
+
+const run = await task.run();
+```
+
+Builder steps are converted into one ordered `.do()` instruction, so hooks, screenshots, output parsing, safety
+options, and limits behave the same as a normal run. `addStep()` is the general-purpose method; `addAct()` is an alias
+for action-oriented steps. `addWait("condition")` waits for a visible condition; `addWait(500)` remains supported and
+maps to `addPause(500)`. `addObserve()`, `addExtract()`, and `addAssert()` add readable intent for common phases. When
+`addExtract()` gets `{ key, shape }`, Automify builds the structured output for you, and multiple extracts are returned
+under `run.parsed[key]`. Short aliases without `add` also work: `step()`, `act()`, `wait()`, `waitFor()`, `pause()`,
+`observe()`, `extract()`, and `assert()`.
+
+Use `task({ mode: "sequential" })` when each step should be its own model run. Sequential mode preserves the same
+builder API, but executes every non-pause step separately, keeps browser or desktop state between steps, and returns a
+`taskSteps` audit trail in addition to the aggregated action `steps`. `addPause(ms)` is deterministic in this mode and
+does not call the model. `addAssert()` asks the model for a structured pass/fail check and fails the task when the
+assertion is not true.
+
+```js
+const run = await browser
+  .task({ mode: "sequential" })
+  .addStep("Fill the first name field from data.")
+  .addStep("Fill the last name field from data.")
+  .addStep("Submit the form.")
+  .addExtract("Return the saved record JSON.", {
+    key: "record",
+    shape: { id: "string", firstName: "string", lastName: "string" }
+  })
+  .addData({ firstName: "Dorothy", lastName: "Vaughan" })
+  .run({ recording: "/tmp/automify-sequential.mp4" });
+
+console.log(run.taskSteps.length);
+console.log(run.parsed.record.id);
+console.log(run.recording.path);
+```
+
+In sequential mode, a run-level `output` applies only to the final non-pause step. Extract outputs still belong on
+`addExtract()` steps; if you define multiple extracts, give each one a `key`. Browser and desktop recordings cover the
+whole sequential task. CLI tasks can run sequentially, but CLI adapters do not record the screen.
+
 - `data` is structured JSON for the task.
 - `evaluate` sends images or text files directly to the model.
-- `shared` and `sharedFiles` expose files inside Docker CLI or Docker desktop runs.
+- `shared` and `sharedFiles` expose files inside Docker CLI, Docker desktop, QEMU virtual CLI, or QEMU virtual desktop runs.
 - `jsonOutput()` requests structured JSON and makes parsed output available as `run.parsed`.
 - `limits.steps` controls the maximum model-action turns before `MaxStepsExceededError`. The default is `100`.
 
+Visual adapters can record a run by polling screenshots and encoding them with `ffmpeg`:
+
+```js
+const run = await browser.do("Run the checkout smoke test.", {
+  recording: "/tmp/automify-checkout.mp4"
+});
+
+console.log(run.recording.path);
+```
+
+Use `recording` or `screenRecording`. Pass a string for the output path, `true` to write a temp MP4, or an object when
+you need control over capture rate and encoding:
+
+```js
+const run = await browser.do("Run the checkout smoke test.", {
+  screenRecording: {
+    path: "/tmp/automify-checkout.mp4",
+    fps: 6,
+    keepFrames: false
+  }
+});
+
+console.log(run.recording.frames);
+```
+
+Recording works for browser and computer-use adapters. CLI adapters do not produce screen recordings. The host process
+needs `ffmpeg` on PATH unless you pass `screenRecording.ffmpegCommand` or a custom `screenRecording.execFile`.
+
 Set max steps on an adapter when most runs need the same limit:
 
 ```js
@@ -491,13 +680,13 @@ Pass `{ parse: false }` if you want Automify to request the Zod-derived JSON Sch
 
 Before running computer use against real accounts or user data:
 
-| Area    | Recommendation                                                                                            |
-| ------- | --------------------------------------------------------------------------------------------------------- |
-| Scope   | Use dedicated accounts, narrow browser allowlists, command policies, and isolated desktops or containers. |
-| Data    | Pass task input through `data`; request application output with `jsonOutput()` instead of parsing prose.  |
-| Safety  | Add human approval for sensitive CLI commands, browser actions, or externally visible operations.         |
-| Privacy | Redact screenshots before model upload when screens can contain secrets or regulated data.                |
-| Audit   | Use `hooks`, `screenshots.actions`, `logFile`, and `trace: true` for workflows that need review.          |
+| Area    | Recommendation                                                                                                |
+| ------- | ------------------------------------------------------------------------------------------------------------- |
+| Scope   | Use dedicated accounts, narrow browser allowlists, command policies, and isolated desktops or containers.     |
+| Data    | Pass task input through `data`; request application output with `jsonOutput()` instead of parsing prose.      |
+| Safety  | Add human approval for sensitive CLI commands, browser actions, or externally visible operations.             |
+| Privacy | Redact screenshots before model upload when screens can contain secrets or regulated data.                    |
+| Audit   | Use `hooks`, `screenshots.actions`, `recording`, `logFile`, and `trace: true` for workflows that need review. |
 
 ## Providers
 
@@ -549,8 +738,10 @@ Use the adapter toolkit when a custom provider needs to emit computer use action
 - `examples/browser-with-safety.js`
 - `examples/cli-basic.js`
 - `examples/cli-docker.js`
+- `examples/cli-qemu.js`
 - `examples/desktop-local.js`
 - `examples/desktop-docker.js`
+- `examples/desktop-qemu.js`
 - `examples/custom-computer.js`
 - `examples/custom-model-adapter.js`
 
@@ -560,16 +751,22 @@ Use the adapter toolkit when a custom provider needs to emit computer use action
 npm test
 npm run test:e2e
 OPENAI_API_KEY=... npm run test:live
+npm run test:live:qemu
+npm run test:live:qemu:desktop
 ```
 
-`npm run test:live` runs `test/e2e/live-openai.e2e.test.js` with `RUN_OPENAI_E2E=1`. By default, it runs the live OpenAI CLI and Docker CLI checks and skips the browser and Docker desktop checks.
+`npm run test:live:qemu` runs only the real QEMU Debian boot smoke test, without OpenAI. `npm run test:live:qemu:desktop` runs the real QEMU desktop smoke test with the default Debian image. Set `AUTOMIFY_QEMU_IMAGE=/path/to/linux.qcow2` only when you want the desktop smoke test or the QEMU live tests to use a custom image. The equivalent direct flags are `RUN_QEMU_DEBIAN_E2E=1 npm run test:e2e` and `RUN_QEMU_DESKTOP_E2E=1 npm run test:e2e`.
+
+`npm run test:live` runs `test/e2e/live-openai.e2e.test.js` with `RUN_OPENAI_E2E=1`. By default, it runs the live OpenAI CLI and Docker CLI checks and skips the browser, Docker desktop, and QEMU checks. Set `RUN_OPENAI_BROWSER_E2E=1` to include the live browser demo tests, including task-builder and recording coverage.
 
 Run every live test:
 
 ```bash
 OPENAI_API_KEY=... \
 RUN_OPENAI_BROWSER_E2E=1 \
-RUN_OPENAI_VIRTUAL_DESKTOP_E2E=1 \
+RUN_OPENAI_DOCKER_DESKTOP_E2E=1 \
+RUN_OPENAI_QEMU_CLI_E2E=1 \
+RUN_OPENAI_QEMU_DESKTOP_E2E=1 \
 npm run test:live
 ```
 
@@ -579,10 +776,14 @@ The equivalent direct command is:
 OPENAI_API_KEY=... \
 RUN_OPENAI_E2E=1 \
 RUN_OPENAI_BROWSER_E2E=1 \
-RUN_OPENAI_VIRTUAL_DESKTOP_E2E=1 \
+RUN_OPENAI_DOCKER_DESKTOP_E2E=1 \
+RUN_OPENAI_QEMU_CLI_E2E=1 \
+RUN_OPENAI_QEMU_DESKTOP_E2E=1 \
 node --test test/e2e/live-openai.e2e.test.js
 ```
 
+Use `AUTOMIFY_QEMU_DEFAULT_IMAGE_URL` to point the default Debian download at a mirror, and `AUTOMIFY_QEMU_IMAGE_CACHE_DIR` to choose the cache directory. By default, Automify caches the downloaded Debian base image and prepared Automify-ready Debian images on the user's computer. CLI cache variants bake the requested `packages` and `additionalAptPackages`; the desktop cache is a separate variant that bakes Xvfb/openbox/xterm/xdotool/scrot so warm desktop boots do not reinstall apt packages. Configure image caching with `defaultImageCache`, for example `defaultImageCache: { dir: "/var/cache/automify-qemu", forcePrepare: true }`. Run `npx automify-qemu-image` to pre-warm the minimal QEMU CLI cache, or add flags such as `--package coreutils --package nodejs` to pre-warm a package-specific CLI cache. Run `npx automify-qemu-image --desktop` to pre-warm the QEMU desktop cache. Run `npx automify-qemu-image --image-url https://example.com/path/linux.qcow2 --cache-dir /var/cache/automify-qemu-custom` to pre-warm an alternate cloud qcow2 cache, then use the same URL and cache directory at runtime with `vm.imageUrl` or `qemuImageUrl` plus `defaultImageCache`. Run `npx automify-qemu-image --force-download` to replace the cached base image and rebuild the prepared image. Local disks passed with `image` or `vm.image` are not prepared by the cache command; they must already be bootable with SSH access. On ARM hosts Automify auto-detects common QEMU UEFI firmware paths; set `AUTOMIFY_QEMU_FIRMWARE` if your QEMU install keeps the firmware elsewhere.
+
 ## License
 
 MIT
@@ -590,3 +791,5 @@ MIT
 ## Disclaimer
 
 Automify is distributed "as is", without warranty of any kind. Automation can control browsers, shells, desktops, files, and external services; you are responsible for how you configure and run it, and for any events associated with that use. To the maximum extent permitted by law, the author is not liable for losses, damages, data loss, service disruption, or other consequences arising from use of the software.
+
+Created by [Aldo Vincenti](https://aldovincenti.com).

package/examples/browser-with-safety.js

@@ -22,17 +22,14 @@ await automify.withBrowser(
     }
   },
   async (browser) => {
-    return browser.do(
-      "Find the contact page and report the support address",
-      {
-        safety: {
-          onCheck: async ({ checks, action }) => {
-            console.log("Safety checks:", checks);
-            console.log("Action:", action);
-            return true;
-          }
+    return browser.do("Find the contact page and report the support address", {
+      safety: {
+        onCheck: async ({ checks, action }) => {
+          console.log("Safety checks:", checks);
+          console.log("Action:", action);
+          return true;
         }
       }
-    );
+    });
   }
 );

package/examples/cli-qemu.js

@@ -0,0 +1,28 @@
+import { initAutomify } from "../src/index.js";
+
+const automify = initAutomify({
+  provider: {
+    type: "openai",
+    apiKey: process.env.OPENAI_API_KEY,
+    model: process.env.OPENAI_MODEL ?? "gpt-5.5"
+  }
+});
+
+const cli = automify.virtualCli({
+  vm: {
+    memory: "2g",
+    cpus: 2
+  },
+  additionalAptPackages: ["coreutils"],
+  shared: { hostPath: process.cwd(), containerPath: "/workspace" },
+  command: {
+    allow: ["cat /etc/os-release", "uname -m", "pwd"]
+  }
+});
+
+try {
+  const result = await cli.do("Run 'cat /etc/os-release', 'uname -m', and 'pwd', then summarize the VM environment.");
+  console.log(result.text);
+} finally {
+  await cli.close();
+}

package/examples/desktop-qemu.js

@@ -0,0 +1,41 @@
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { createVirtualDesktopComputer, initAutomify } from "../src/index.js";
+
+const automify = initAutomify({
+  provider: {
+    type: "openai",
+    apiKey: process.env.OPENAI_API_KEY,
+    model: process.env.OPENAI_MODEL ?? "gpt-5.5"
+  }
+});
+
+const computer = await createVirtualDesktopComputer({
+  vm: {
+    memory: "2g",
+    cpus: 2
+  },
+  desktop: {
+    startupCommand: "xterm"
+  }
+});
+
+try {
+  const desktop = automify.computer({ computer });
+  const result = await desktop.do(
+    "Use the open terminal to run 'uname -a' and summarize the VM system information shown on screen.",
+    {
+      screenshots: {
+        initial: join(tmpdir(), "automify-qemu-desktop-initial.png"),
+        final: join(tmpdir(), "automify-qemu-desktop-final.png")
+      },
+      limits: { steps: 12 }
+    }
+  );
+
+  console.log(result.text);
+  console.log(result.finalScreenshot);
+} finally {
+  await computer.close();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "automify",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "AI computer use for browser, CLI, and desktop in Node.js.",
   "homepage": "https://aldovincenti.github.io/automify",
   "bugs": {
@@ -14,7 +14,8 @@
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "bin": {
-    "automify-install-desktop": "./scripts/install-desktop.js"
+    "automify-install-desktop": "./scripts/install-desktop.js",
+    "automify-qemu-image": "./scripts/qemu-image.js"
   },
   "exports": {
     ".": {
@@ -42,6 +43,8 @@
     "test": "node --test test/*.test.js",
     "test:e2e": "node --test test/e2e/*.e2e.test.js",
     "test:live": "RUN_OPENAI_E2E=1 node --test test/e2e/live-openai.e2e.test.js",
+    "test:live:qemu": "RUN_QEMU_DEBIAN_E2E=1 node --test test/e2e/qemu-runtimes.e2e.test.js",
+    "test:live:qemu:desktop": "RUN_QEMU_DESKTOP_E2E=1 node --test --test-name-pattern \"QEMU virtual desktop\" test/e2e/desktop-runtimes.e2e.test.js",
     "format": "prettier --write .",
     "format:check": "prettier --check ."
   },

package/scripts/generate-argument-reference.js

@@ -2,7 +2,9 @@ import { writeFile } from "node:fs/promises";
 import { argumentReference } from "../src/lib/argument-reference.js";
 
 const rows = argumentReference
-  .map((entry) => `| \`${entry.surface}\` | ${entry.preferred.map((name) => `\`${name}\``).join(", ")} | ${entry.notes} |`)
+  .map(
+    (entry) => `| \`${entry.surface}\` | ${entry.preferred.map((name) => `\`${name}\``).join(", ")} | ${entry.notes} |`
+  )
   .join("\n");
 
 const markdown = `# Automify Argument Reference