automify 0.2.0 → 0.3.1

package/scripts/qemu-image.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { DEFAULT_QEMU_DESKTOP_PACKAGES } from "../src/lib/qemu-desktop-computer.js";
+import { ensureDefaultQemuImageCache } from "../src/lib/qemu-runtime.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h")) {
+  printHelp();
+  process.exit(0);
+}
+
+const options = parseArgs(args);
+
+console.log("Preparing Automify QEMU default Debian image cache.");
+if (options.desktop) {
+  console.log("Desktop cache enabled: the prepared image will include the default QEMU desktop packages.");
+} else if (options.packages.length > 0) {
+  console.log("CLI cache enabled: the prepared image will include the requested apt packages.");
+} else {
+  console.log("CLI cache enabled: the prepared image will stay minimal for QEMU virtual CLI runs.");
+}
+if (options.defaultImageCache.forceDownload) {
+  console.log("Force download enabled: the cached base image will be replaced.");
+}
+if (options.defaultImageCache.forcePrepare) {
+  console.log("Force prepare enabled: the cached prepared image will be rebuilt.");
+}
+if (options.defaultImageCache.prepared === false) {
+  console.log("Prepared image disabled: only the base Debian qcow2 will be downloaded.");
+}
+
+try {
+  const cache = await ensureDefaultQemuImageCache({
+    qemuCommand: options.qemuCommand,
+    qemuImgCommand: options.qemuImgCommand,
+    imageUrl: options.imageUrl,
+    defaultImageCache: options.defaultImageCache,
+    preparedImageProfile: options.desktop ? "desktop" : undefined,
+    preparedPackages: options.desktop ? uniquePackages([...DEFAULT_QEMU_DESKTOP_PACKAGES, ...options.packages]) : options.packages,
+    vmName: "automify-qemu-image"
+  });
+
+  console.log(`Base image: ${cache.baseImage}`);
+  if (cache.preparedImage) {
+    console.log(`Prepared image: ${cache.preparedImage}`);
+    console.log(`SSH key: ${cache.sshKeyPath}`);
+  }
+  console.log("Automify QEMU image cache is ready.");
+} catch (error) {
+  console.error(error?.stack || error?.message || String(error));
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const result = {
+    defaultImageCache: {},
+    desktop: false,
+    packages: []
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case "--force":
+      case "--force-download":
+        result.defaultImageCache.forceDownload = true;
+        result.defaultImageCache.forcePrepare = true;
+        break;
+      case "--force-prepare":
+        result.defaultImageCache.forcePrepare = true;
+        break;
+      case "--no-prepare":
+        result.defaultImageCache.prepared = false;
+        break;
+      case "--desktop":
+        result.desktop = true;
+        break;
+      case "--package":
+        result.packages.push(requiredValue(argv, ++index, arg));
+        break;
+      case "--cache-dir":
+        result.defaultImageCache.dir = requiredValue(argv, ++index, arg);
+        break;
+      case "--prepared-cache-dir":
+        result.defaultImageCache.preparedDir = requiredValue(argv, ++index, arg);
+        break;
+      case "--image-url":
+        result.imageUrl = requiredValue(argv, ++index, arg);
+        break;
+      case "--qemu":
+      case "--qemu-command":
+        result.qemuCommand = requiredValue(argv, ++index, arg);
+        break;
+      case "--qemu-img":
+      case "--qemu-img-command":
+        result.qemuImgCommand = requiredValue(argv, ++index, arg);
+        break;
+      default:
+        console.error(`Unknown option: ${arg}`);
+        printHelp();
+        process.exit(1);
+    }
+  }
+
+  return result;
+}
+
+function uniquePackages(packages) {
+  return [...new Set(packages.map((pkg) => String(pkg).trim()).filter(Boolean))];
+}
+
+function requiredValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith("--")) {
+    console.error(`${flag} requires a value.`);
+    process.exit(1);
+  }
+  return value;
+}
+
+function printHelp() {
+  console.log(`Usage: npx automify-qemu-image [options]
+
+Prepare or refresh the default Debian image cache used by Automify QEMU adapters.
+Without --desktop, this pre-warms the minimal QEMU virtual CLI cache.
+
+Options:
+  --force-download        Re-download the base Debian qcow2 and rebuild prepared image
+  --force-prepare         Rebuild only the prepared image
+  --no-prepare            Download only the base Debian qcow2
+  --desktop               Prepare the QEMU desktop cache variant
+  --package <name>        Add an apt package to the prepared cache
+  --cache-dir <path>      Cache root for base and prepared images
+  --prepared-cache-dir <path>
+                          Cache directory for prepared images
+  --image-url <url>       Override the default Debian qcow2 URL
+  --qemu <command>        Override qemu-system command
+  --qemu-img <command>    Override qemu-img command
+  --help                  Show this help
+
+Examples:
+  npx automify-qemu-image            # pre-warm the QEMU CLI cache
+  npx automify-qemu-image --package coreutils --package nodejs
+  npx automify-qemu-image --desktop  # pre-warm the QEMU desktop cache
+  npx automify-qemu-image --force-download
+  npx automify-qemu-image --cache-dir ${root}/.automify-qemu-cache
+  npx automify-qemu-image --image-url https://example.com/path/linux.qcow2 --cache-dir ${root}/.automify-qemu-custom
+`);
+}

package/src/index.d.ts

@@ -13,6 +13,7 @@ export type ComputerAction =
   | { type: string; [key: string]: unknown };
 
 export type Screenshot = string | ArrayBuffer | Uint8Array | Buffer;
+export type ScreenRecordingInput = boolean | string | ScreenRecordingOptions;
 export type DomainRule = string | RegExp | ((url: URL) => boolean);
 export type CommandRule = string | RegExp | ((command: string) => boolean);
 export type DebugLogger = boolean | ((message: string, details?: unknown) => void);
@@ -88,6 +89,30 @@ export interface JsonOutputOptions {
   parse?: boolean;
 }
 
+export interface ScreenRecordingOptions {
+  enabled?: boolean;
+  path?: string;
+  fps?: number;
+  intervalMs?: number;
+  captureIntervalMs?: number;
+  framesDir?: string;
+  keepFrames?: boolean;
+  ffmpegCommand?: string;
+  command?: string;
+  encodingTimeoutMs?: number;
+  timeoutMs?: number;
+  execFile?: (...args: unknown[]) => Promise<unknown> | unknown;
+}
+
+export interface ScreenRecordingResult {
+  path: string;
+  bytes?: number;
+  frames?: number;
+  fps?: number;
+  startedAt?: string;
+  stoppedAt?: string;
+}
+
 export function jsonOutput(
   name: string,
   shape: JsonOutputShape | Record<string, unknown>,
@@ -142,6 +167,8 @@ export interface AutomifyOptions {
   finalScreenshot?: string;
   actionScreenshots?: string;
   screenshots?: DoScreenshotsOptions;
+  recording?: ScreenRecordingInput;
+  screenRecording?: ScreenRecordingInput;
   trace?: boolean;
   silent?: boolean;
   debug?: DebugLogger;
@@ -161,6 +188,11 @@ export type DockerComputerAutomifyOptions = Omit<AutomifyOptions, "computer"> &
     computer?: ComputerAdapter & { session: DockerDesktopSession; sharedFolder?: VirtualSharedFolderData };
   };
 
+export type VirtualComputerAutomifyOptions = Omit<AutomifyOptions, "computer"> &
+  VirtualDesktopComputerOptions & {
+    computer?: ComputerAdapter & { session: QemuDesktopSession; sharedFolder?: VirtualSharedFolderData };
+  };
+
 export interface LocalComputerAutomifyOptions extends Omit<AutomifyOptions, "computer">, LocalDesktopComputerOptions {
   computer?: ComputerAdapter;
 }
@@ -175,6 +207,12 @@ export interface LocalDesktopComputerOptions {
   actionDelayMs?: number;
   instructions?: string;
   screenshotPath?: string;
+  /**
+   * Defaults to "local-desktop", giving the local adapter an exclusive
+   * cross-process lock. Override only when you know this runner is attached to
+   * an independent desktop session or isolated test double.
+   */
+  lockResource?: string;
   /**
    * Screenshot pixels per native mouse coordinate. On macOS Retina displays the
    * default is inferred as 2; use 1 for non-Retina external displays.
@@ -381,7 +419,145 @@ export type DockerDesktopComputerOptions =
   | (DockerDesktopComputerBaseOptions & { startupCommand: string })
   | (DockerDesktopComputerBaseOptions & { desktop: DockerDesktopOptions });
 
-export type VirtualDesktopComputerOptions = DockerDesktopComputerOptions;
+export interface QemuSshOptions {
+  command?: string;
+  host?: string;
+  port?: number;
+  user?: string;
+  keyPath?: string;
+  options?: string[];
+  timeoutMs?: number;
+  sudo?: boolean;
+}
+
+export interface QemuVmOptions {
+  qemu?: string;
+  qemuCommand?: string;
+  qemuImgCommand?: string;
+  imageCacheDir?: string;
+  imageUrl?: string;
+  defaultImageCache?: QemuDefaultImageCacheOptions;
+  image?: string;
+  diskImage?: string;
+  diskFormat?: "qcow2" | "raw" | string;
+  name?: string;
+  existing?: boolean;
+  keep?: boolean;
+  memory?: number | string;
+  cpus?: number | string;
+  accel?: "hvf" | "kvm" | "whpx" | "tcg" | string;
+  machine?: string;
+  cpu?: string;
+  firmware?: string;
+  network?: boolean;
+  networkDevice?: string;
+  extraArgs?: string[];
+  timeoutMs?: number;
+}
+
+export type QemuDefaultImageCacheOptions =
+  | boolean
+  | {
+      /**
+       * Cache root for the downloaded base image and prepared image subdirectory.
+       */
+      dir?: string;
+      /**
+       * Cache directory for downloaded base images. Defaults to dir when provided.
+       */
+      imageCacheDir?: string;
+      /**
+       * Cache directory for Automify-ready prepared images. Defaults to `${dir}/prepared`.
+       */
+      preparedDir?: string;
+      /**
+       * Defaults to true. When true, Automify caches a booted Debian image with
+       * the automify SSH user already provisioned, then creates runtime overlays
+       * from that image.
+       */
+      prepared?: boolean;
+      /**
+       * Re-download the Debian base qcow2 and rebuild the prepared image.
+       */
+      forceDownload?: boolean;
+      /**
+       * Rebuild the prepared image even if one already exists.
+       */
+      forcePrepare?: boolean;
+    };
+
+export interface VirtualDesktopComputerBaseOptions {
+  preset?: VirtualDesktopPreset;
+  vm?: QemuVmOptions;
+  qemuCommand?: string;
+  qemuImgCommand?: string;
+  qemuImageCacheDir?: string;
+  qemuImageUrl?: string;
+  defaultImageCache?: QemuDefaultImageCacheOptions;
+  image?: string;
+  diskImage?: string;
+  diskFormat?: "qcow2" | "raw" | string;
+  vmName?: string;
+  existingVM?: boolean;
+  keepVM?: boolean;
+  start?: boolean;
+  ssh?: QemuSshOptions;
+  sshCommand?: string;
+  sshKeygenCommand?: string;
+  sshHost?: string;
+  sshPort?: number;
+  sshUser?: string;
+  sshKeyPath?: string;
+  sshOptions?: string[];
+  sshTimeoutMs?: number;
+  sudo?: boolean;
+  display?: string;
+  viewport?: ViewportOptions;
+  displayWidth?: number;
+  displayHeight?: number;
+  displayDepth?: number;
+  environment?: ComputerUseEnvironment;
+  instructions?: string;
+  desktop?: DockerDesktopOptions;
+  startupCommand?: string;
+  windowManagerCommand?: string;
+  installDependencies?: boolean;
+  desktopPackages?: string[];
+  additionalAptPackages?: string[];
+  memory?: number | string;
+  cpus?: number | string;
+  accel?: "hvf" | "kvm" | "whpx" | "tcg" | string;
+  machine?: string;
+  cpu?: string;
+  firmware?: string;
+  network?: boolean;
+  networkDevice?: string;
+  extraQemuArgs?: string[];
+  shared?: VirtualSharedFolderInput;
+  sharedFolder?: VirtualSharedFolderInput;
+  sharedFiles?: VirtualSharedFileInput[];
+  files?: VirtualSharedFileInput[];
+  sharedMode?: "virtfs" | "none" | string;
+  sharedTag?: string;
+  sharedSecurityModel?: string;
+  waitMs?: number;
+  startupTimeoutMs?: number;
+  qemuTimeoutMs?: number;
+  commandTimeoutMs?: number;
+  screenshotMaxBuffer?: number;
+  screenshotSettleMs?: number;
+  fetchImpl?: typeof fetch;
+  execFile?: (...args: unknown[]) => Promise<{ stdout?: Buffer | string; stderr?: Buffer | string }>;
+  spawn?: (...args: unknown[]) => unknown;
+  silent?: boolean;
+  debug?: DebugLogger;
+  logFile?: string;
+  onUnknownAction?: (action: ComputerAction, context?: Record<string, unknown>) => Promise<void> | void;
+}
+
+export type VirtualDesktopComputerOptions =
+  | (VirtualDesktopComputerBaseOptions & { startupCommand: string })
+  | (VirtualDesktopComputerBaseOptions & { desktop: DockerDesktopOptions });
 
 export type VirtualSharedFolderInput =
   | true
@@ -427,7 +603,17 @@ export class DockerDesktopSession {
   close(): Promise<void>;
 }
 
-export { DockerDesktopSession as DockerVirtualDesktopSession };
+export class QemuDesktopSession {
+  constructor(options?: VirtualDesktopComputerOptions);
+  readonly name: string;
+  readonly display: string;
+  readonly width: number;
+  readonly height: number;
+  start(): Promise<void>;
+  execute(action: ComputerAction): Promise<void>;
+  screenshot(): Promise<Buffer>;
+  close(): Promise<void>;
+}
 
 export interface OpenAIProviderConfig {
   type: "openai";
@@ -486,6 +672,8 @@ export interface InitAutomifyOptions {
   finalScreenshot?: string;
   actionScreenshots?: string;
   screenshots?: DoScreenshotsOptions;
+  recording?: ScreenRecordingInput;
+  screenRecording?: ScreenRecordingInput;
   trace?: boolean;
   silent?: boolean;
   debug?: DebugLogger;
@@ -525,6 +713,8 @@ export interface DoOptions {
   finalScreenshot?: string;
   actionScreenshots?: string;
   screenshots?: DoScreenshotsOptions;
+  recording?: ScreenRecordingInput;
+  screenRecording?: ScreenRecordingInput;
   trace?: boolean;
   silent?: boolean;
   onSafetyCheck?: (event: {
@@ -545,6 +735,7 @@ export interface DoScreenshotsOptions {
   final?: string;
   actions?: string;
   actionScreenshots?: string;
+  recording?: ScreenRecordingInput;
 }
 
 export interface DoScreenshotOptions {
@@ -592,6 +783,8 @@ export interface CliCommandOptions {
 export interface AutomifyResult {
   response: Record<string, unknown>;
   steps: Array<Record<string, unknown>>;
+  taskSteps?: TaskStepResult[];
+  extracts?: Record<string, unknown>;
   trace?: Array<Record<string, unknown>>;
   ok: boolean;
   status: "succeeded";
@@ -603,6 +796,7 @@ export interface AutomifyResult {
     path: string;
     bytes?: number;
   };
+  recording?: ScreenRecordingResult;
 }
 
 export interface AutomifyCompleteEvent {
@@ -621,10 +815,80 @@ export interface AutomifyCompleteEvent {
 export class Automify {
   constructor(options: AutomifyOptions);
   do(instruction: string, options?: DoOptions): Promise<AutomifyResult>;
+  task(options?: TaskRunOptions): AutomifyTask;
+  addStep(instruction: string, options?: TaskStepOptions): AutomifyTask;
+  addAct(instruction: string, options?: TaskStepOptions): AutomifyTask;
+  addWait(conditionOrMs?: string | number, options?: TaskStepOptions): AutomifyTask;
+  addWaitFor(condition?: string, options?: TaskStepOptions): AutomifyTask;
+  addPause(ms: number, options?: TaskStepOptions): AutomifyTask;
+  addObserve(instruction: string, options?: TaskStepOptions): AutomifyTask;
+  addExtract(instruction: string, options?: TaskExtractOptions | OutputFormat): AutomifyTask;
+  addAssert(instruction: string, options?: TaskStepOptions): AutomifyTask;
 }
 
 export function createAutomify(options: AutomifyOptions): Automify;
 
+export type TaskMode = "single" | "sequential";
+export type TaskRunOptions = (DoOptions | CliAutomifyDoOptions) & { mode?: TaskMode };
+
+export interface TaskStepOptions {
+  label?: string;
+  notes?: string;
+}
+
+export interface TaskExtractOptions extends TaskStepOptions {
+  key?: string;
+  shape?: JsonOutputShape | Record<string, unknown>;
+  schema?: JsonOutputShape | Record<string, unknown>;
+  output?: OutputFormat;
+  description?: string;
+  strict?: boolean;
+  parse?: boolean;
+}
+
+export interface TaskStepResult {
+  index: number;
+  type: "step" | "wait" | "pause" | "observe" | "extract" | "assert" | string;
+  instruction: string;
+  label?: string;
+  notes?: string;
+  status: "succeeded" | "failed";
+  durationMs?: number;
+  responseId?: string;
+  text?: string;
+  parsed?: unknown;
+  modelSteps?: number;
+  error?: string;
+}
+
+export class AutomifyTask {
+  constructor(automify: Automify | CliAutomify, options?: TaskRunOptions);
+  addStep(instruction: string, options?: TaskStepOptions): this;
+  step(instruction: string, options?: TaskStepOptions): this;
+  addAct(instruction: string, options?: TaskStepOptions): this;
+  act(instruction: string, options?: TaskStepOptions): this;
+  addWait(conditionOrMs?: string | number, options?: TaskStepOptions): this;
+  wait(conditionOrMs?: string | number, options?: TaskStepOptions): this;
+  addWaitFor(condition?: string, options?: TaskStepOptions): this;
+  waitFor(condition?: string, options?: TaskStepOptions): this;
+  addPause(ms: number, options?: TaskStepOptions): this;
+  pause(ms: number, options?: TaskStepOptions): this;
+  addObserve(instruction: string, options?: TaskStepOptions): this;
+  observe(instruction: string, options?: TaskStepOptions): this;
+  addExtract(instruction: string, options?: TaskExtractOptions | OutputFormat): this;
+  extract(instruction: string, options?: TaskExtractOptions | OutputFormat): this;
+  addAssert(instruction: string, options?: TaskStepOptions): this;
+  assert(instruction: string, options?: TaskStepOptions): this;
+  addData(data: Record<string, unknown> | unknown): this;
+  withData(data: Record<string, unknown> | unknown): this;
+  withOptions(options?: TaskRunOptions): this;
+  toInstruction(): string;
+  run(options?: TaskRunOptions): Promise<AutomifyResult | CliAutomifyResult>;
+  do(options?: TaskRunOptions): Promise<AutomifyResult | CliAutomifyResult>;
+}
+
+export function createTask(automify: Automify | CliAutomify, options?: TaskRunOptions): AutomifyTask;
+
 export function createComputerAutomify(options: AutomifyOptions): Automify;
 
 export interface InitializedAutomify {
@@ -642,7 +906,10 @@ export interface InitializedAutomify {
   localComputer(
     options?: Omit<LocalComputerAutomifyOptions, "openaiApiKey" | "client">
   ): Promise<LocalComputerAutomify>;
-  virtualCli(options?: Omit<DockerCliAutomifyOptions, "openaiApiKey" | "client">): DockerCliAutomify;
+  virtualComputer(
+    options?: Omit<VirtualComputerAutomifyOptions, "openaiApiKey" | "client">
+  ): Promise<VirtualComputerAutomify>;
+  virtualCli(options?: Omit<VirtualCliAutomifyOptions, "openaiApiKey" | "client">): VirtualCliAutomify;
   computer(options: Omit<AutomifyOptions, "openaiApiKey" | "client">): Automify;
   custom(options: Omit<AutomifyOptions, "openaiApiKey" | "client">): Automify;
 }
@@ -720,6 +987,12 @@ export class DockerComputerAutomify extends Automify {
   close(): Promise<void>;
 }
 
+export class VirtualComputerAutomify extends Automify {
+  session: QemuDesktopSession;
+  sharedFolder?: VirtualSharedFolderData;
+  close(): Promise<void>;
+}
+
 export class LocalComputerAutomify extends Automify {
   close(): Promise<void>;
 }
@@ -730,6 +1003,9 @@ export function withBrowserAutomify<T>(
   run: (automify: BrowserAutomify) => Promise<T> | T
 ): Promise<T>;
 export function createDockerComputerAutomify(options?: DockerComputerAutomifyOptions): Promise<DockerComputerAutomify>;
+export function createVirtualComputerAutomify(
+  options?: VirtualComputerAutomifyOptions
+): Promise<VirtualComputerAutomify>;
 export function createLocalComputerAutomify(options?: LocalComputerAutomifyOptions): Promise<LocalComputerAutomify>;
 
 export function createLocalDesktopComputer(options?: LocalDesktopComputerOptions): Promise<ComputerAdapter>;
@@ -740,12 +1016,11 @@ export function createDockerDesktopComputer(
   options?: DockerDesktopComputerOptions
 ): Promise<ComputerAdapter & { session: DockerDesktopSession; sharedFolder?: VirtualSharedFolderData }>;
 export function createVirtualDesktopComputer(
-  options?: DockerDesktopComputerOptions
-): Promise<ComputerAdapter & { session: DockerDesktopSession; sharedFolder?: VirtualSharedFolderData }>;
+  options?: VirtualDesktopComputerOptions
+): Promise<ComputerAdapter & { session: QemuDesktopSession; sharedFolder?: VirtualSharedFolderData }>;
 export function defaultDockerDesktopImage(): string;
 export function defaultVirtualDesktopImage(): string;
 export function dockerDesktopDockerfile(): string;
-export function virtualDesktopDockerfile(): string;
 
 export interface CliAutomifyOptions extends Omit<InitAutomifyOptions, "model" | "onComplete"> {
   preset?: CliPreset;
@@ -818,6 +1093,8 @@ export type CliAutomifyDoOptions = CliDoOptions;
 export interface CliAutomifyResult {
   response: Record<string, unknown>;
   steps: Array<Record<string, unknown>>;
+  taskSteps?: TaskStepResult[];
+  extracts?: Record<string, unknown>;
   ok: boolean;
   status: "succeeded";
   completed: boolean;
@@ -842,6 +1119,15 @@ export interface CliAutomifyCompleteEvent {
 export class CliAutomify {
   constructor(options: CliAutomifyOptions);
   do(instruction: string, options?: CliAutomifyDoOptions): Promise<CliAutomifyResult>;
+  task(options?: TaskRunOptions): AutomifyTask;
+  addStep(instruction: string, options?: TaskStepOptions): AutomifyTask;
+  addAct(instruction: string, options?: TaskStepOptions): AutomifyTask;
+  addWait(conditionOrMs?: string | number, options?: TaskStepOptions): AutomifyTask;
+  addWaitFor(condition?: string, options?: TaskStepOptions): AutomifyTask;
+  addPause(ms: number, options?: TaskStepOptions): AutomifyTask;
+  addObserve(instruction: string, options?: TaskStepOptions): AutomifyTask;
+  addExtract(instruction: string, options?: TaskExtractOptions | OutputFormat): AutomifyTask;
+  addAssert(instruction: string, options?: TaskStepOptions): AutomifyTask;
 }
 
 export function createCliAutomify(options: CliAutomifyOptions): CliAutomify;
@@ -936,7 +1222,60 @@ export interface DockerCliAutomifyOptions extends CliAutomifyOptions {
   execFile?: (...args: unknown[]) => Promise<{ stdout?: Buffer | string; stderr?: Buffer | string }>;
 }
 
-export type VirtualCliAutomifyOptions = DockerCliAutomifyOptions;
+export interface VirtualCliAutomifyOptions extends CliAutomifyOptions {
+  preset?: VirtualCliPreset;
+  session?: QemuCliSession;
+  vm?: QemuVmOptions;
+  qemuCommand?: string;
+  qemuImgCommand?: string;
+  qemuImageCacheDir?: string;
+  qemuImageUrl?: string;
+  defaultImageCache?: QemuDefaultImageCacheOptions;
+  image?: string;
+  diskImage?: string;
+  diskFormat?: "qcow2" | "raw" | string;
+  vmName?: string;
+  existingVM?: boolean;
+  keepVM?: boolean;
+  workdir?: string;
+  workspacePath?: string;
+  guestCwd?: string;
+  startupCommand?: string;
+  packages?: string[];
+  additionalAptPackages?: string[];
+  installDependencies?: boolean;
+  memory?: number | string;
+  cpus?: number | string;
+  accel?: "hvf" | "kvm" | "whpx" | "tcg" | string;
+  machine?: string;
+  cpu?: string;
+  firmware?: string;
+  network?: boolean;
+  networkDevice?: string;
+  extraQemuArgs?: string[];
+  ssh?: QemuSshOptions;
+  sshCommand?: string;
+  sshKeygenCommand?: string;
+  sshHost?: string;
+  sshPort?: number;
+  sshUser?: string;
+  sshKeyPath?: string;
+  sshOptions?: string[];
+  sshTimeoutMs?: number;
+  sudo?: boolean;
+  shared?: VirtualSharedFolderInput;
+  sharedFolder?: VirtualSharedFolderInput;
+  sharedFiles?: VirtualSharedFileInput[];
+  files?: VirtualSharedFileInput[];
+  sharedMode?: "virtfs" | "none" | string;
+  sharedTag?: string;
+  sharedSecurityModel?: string;
+  startupTimeoutMs?: number;
+  qemuTimeoutMs?: number;
+  commandMaxBuffer?: number;
+  execFile?: (...args: unknown[]) => Promise<{ stdout?: Buffer | string; stderr?: Buffer | string }>;
+  spawn?: (...args: unknown[]) => unknown;
+}
 
 export class DockerCliSession {
   constructor(options?: DockerCliAutomifyOptions);
@@ -958,10 +1297,29 @@ export class DockerCliAutomify extends CliAutomify {
   close(): Promise<void>;
 }
 
-export { DockerCliAutomify as VirtualCliAutomify, DockerCliSession as DockerVirtualCliSession };
-
 export function createDockerCliAutomify(options: DockerCliAutomifyOptions): DockerCliAutomify;
-export function createVirtualCliAutomify(options: DockerCliAutomifyOptions): DockerCliAutomify;
+export class QemuCliSession {
+  constructor(options?: VirtualCliAutomifyOptions);
+  readonly name: string;
+  readonly cwd: string;
+  readonly sharedFolder?: { data: VirtualSharedFolderData };
+  start(): Promise<void>;
+  run(
+    command: string,
+    options?: { cwd?: string; env?: Record<string, string>; timeoutMs?: number }
+  ): Promise<Record<string, unknown>>;
+  close(): Promise<void>;
+}
+export { QemuCliSession as QemuVirtualCliSession };
+
+export class VirtualCliAutomify extends CliAutomify {
+  session: QemuCliSession;
+  readonly sharedFolder?: VirtualSharedFolderData;
+  do(instruction: string, options?: CliAutomifyDoOptions): Promise<CliAutomifyResult>;
+  close(): Promise<void>;
+}
+
+export function createVirtualCliAutomify(options: VirtualCliAutomifyOptions): VirtualCliAutomify;
 
 export class OpenAIResponsesClient {
   constructor(options: {