@bastani/atomic 0.9.56-alpha.1 → 0.9.57-alpha.1

package/docs/workflows/authoring.md

@@ -519,169 +519,96 @@ After exit is selected, new tracked work and retained stage operations are refus
 
 On resume of an unfinished tool, a successful exit cannot skip that tool. Restore its matching call before new tracked work; otherwise Atomic reports `insufficient_state: replay topology mismatch`. Intentional failed, blocked, cancelled, or skipped exits remain available.
 
-<a id="desktop-verification-with-cua-driver-in-ctx-tool" />
+<a id="desktop-verification-with-agent-desktop-in-ctx-tool" />
 
-### Desktop verification with Cua Driver in `ctx.tool`
+### Desktop verification with agent-desktop in `ctx.tool`
 
-When a model chooses each desktop action, an authored model stage loads the bundled `cua-driver` skill and runs one-shot `cua-driver call <tool>` commands; see [Computer use](/computer-use#desktop-automation-with-cua-driver) for the face rule, installation, telemetry, and readiness. When your workflow's TypeScript owns the sequence and the postcondition, run the scenario with the [`@trycua/cua-driver`](https://www.npmjs.com/package/@trycua/cua-driver) TypeScript SDK inside `ctx.tool(name, args, fn, { timeoutMs })` so the observe → act → re-observe → assert loop is a durable, replayable node rather than a transcript.
+When a model chooses each desktop action, an authored model stage loads the bundled `agent-desktop` skill and runs one-shot `agent-desktop` commands; see [Computer use](/computer-use#desktop-automation-with-agent-desktop) for the rule, installation, and readiness. When your workflow's TypeScript owns the sequence and the postcondition, call the `agent-desktop` CLI from inside `ctx.tool(name, args, fn, { timeoutMs })` so the observe → act → verify loop is a durable, replayable node rather than a transcript. agent-desktop has no TypeScript SDK: every command prints one JSON envelope (`ok`, then `data` or `error`), and that envelope is the contract.
 
-Prerequisites and setup, each as one bounded attempt:
+The only prerequisite is the CLI on the host: `npm install -g agent-desktop` (Node 18 or later), approving its install script if npm blocks it. Do not install it from inside the run. The readiness preflight below reports a missing install as a limitation instead. The executable carries its own guides (`agent-desktop skills get desktop`), and Atomic bundles the skill, so skip `npx skills add` and leave existing user-level skills alone.
 
-- `node` (preferred) or `bun` on the host. If neither is present, install one in a bounded attempt (Node via [fnm](https://github.com/Schniz/fnm) with `fnm install --lts` or the host's package manager, Bun via `curl -fsSL https://bun.sh/install | bash`) and report what the installer did; if the install is refused or fails, report that as the limitation rather than retrying.
-- The `cua-driver` executable (`cua-driver --version`), installed with upstream's one-line installer if missing, followed by `cua-driver telemetry disable` once.
-- The SDK installed at the exact driver version into a scratch directory outside the user's repository, for example `npm install @trycua/cua-driver@0.36.0 --prefix ~/.cache/atomic-cua`. The package ships per-platform native optional dependencies. Daemon-backed clients verify contract, tool-schema, capability, and protocol versions before each action and refuse on mismatch, so the pin must match `cua-driver --version`.
+The workflow below checks readiness in its own `ctx.tool` first, so a missing install, a missing macOS permission, or an unreachable Linux accessibility bus ends the run with `ctx.exit({ status: "blocked", reason })`. A blocked author exit is terminal and not resumable (see [Early exit with `ctx.exit()`](#early-exit-with-ctx-exit)), and the preflight's `{ ready: false }` result is a completed, cached checkpoint, so after the user fixes the problem start a new run: its fresh preflight checks again instead of replaying the cached result. The scenario tool spawns one `agent-desktop` process per command without a shell (on Windows it starts the package's native executable, not npm's `.cmd` shim, so no argument is parsed by `cmd.exe`), saves each result's JSON and both screenshots as evidence, forwards `signal` so a quit or targeted abort kills the child, and throws anything but `verified`, so a failed scenario fails the node.
 
-The executable installer does not install an agent skill. Atomic bundles the skill, so skip upstream's optional `cua-driver skills install`, `cua-driver skills update`, and `clawhub install @cua/driver` steps; leave existing user-level skills alone.
-
-The scenario itself is a small script in that scratch directory. It acquires the driver with `CuaDriver.connect(undefined)` when a daemon is running, so it reuses the daemon's permission identity (on macOS, `CuaDriver.app`'s Accessibility and Screen Recording grants) and the persisted telemetry-off preference; upstream describes `connect()` as a compatibility and app-hosting path, which is exactly the role it plays here. Only when no daemon is reachable does it fall back to `CuaDriver.create(undefined)`, which loads the runtime into the node process. On macOS that in-process fallback attributes permissions to the node host, normally the terminal app, as a **separate grant** from the app's; `checkPermissions` is then read-only, and the host must fully quit and relaunch after granting. Save it as `~/.cache/atomic-cua/verify-counter.mjs`:
-
-```js
-// Reads {"daemon":true|false,"artifactsDir":"..."} from argv[2]; prints one JSON result line.
-// Replace the app name, window title, element labels, and postcondition with ones you control.
+```ts
+import { execFileSync, spawn } from "node:child_process";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import {
-  ActionTarget, ClickButton, ClickInput, ClickPosition, CuaDriver,
-  GetWindowStateInput, InputDeliveryMode, ListAppsInput, ListWindowsInput,
-} from "@trycua/cua-driver";
-
-const { daemon, artifactsDir } = JSON.parse(process.argv[2]);
-mkdirSync(artifactsDir, { recursive: true });
-const unique = (items, what) => {
-  if (items.length !== 1) throw new Error(`Expected one ${what}, found ${items.length}`);
-  return items[0];
-};
-const finish = (result, detail) => {
-  process.stdout.write(`${JSON.stringify({ result, detail })}\n`);
-  process.exitCode = result === "verified" ? 0 : 1;
-};
+import { workflow } from "@bastani/atomic/workflows";
+import { Type } from "typebox";
 
-// The wrapper already set CUA_DRIVER_RS_TELEMETRY_ENABLED=false in this process's environment
-// before the driver was constructed; the SDK is one of the faces that reports telemetry by default.
-const driver = daemon ? CuaDriver.connect(undefined) : CuaDriver.create(undefined);
-try {
-  const apps = await driver.listApps(ListAppsInput.new({}));
-  const app = unique(apps.apps.filter((a) => a.name === "Window Demo" && a.running), "app");
-  const windows = await driver.listWindows(ListWindowsInput.new({ pid: app.pid, onScreenOnly: true }));
-  const window = unique(windows.windows.filter((w) => w.title === "Counter"), "window");
-  const target = new ActionTarget.Window({ pid: app.pid, windowId: window.windowId });
-  const snapshot = async (label) => {
-    const state = await driver.getWindowState(
-      GetWindowStateInput.new({
-        pid: app.pid, windowId: window.windowId,
-        includeAccessibilityTree: true, includeScreenshot: true,
-        screenshotOutFile: join(artifactsDir, `${label}.png`),
-      }),
-    );
-    if (state.degraded || state.truncated) throw new Error(`${label} snapshot is degraded or truncated`);
-    // Keep the whole result (snapshot id, screenshot reference, degraded/truncated flags), not just
-    // the elements, so the retained tree is provably from a complete snapshot. Ids are bigint.
-    const json = JSON.stringify(state, (_key, value) => (typeof value === "bigint" ? value.toString() : value), 2);
-    writeFileSync(join(artifactsDir, `${label}.json`), json);
-    return state;
+type Envelope = {
+  ok: boolean;
+  data?: {
+    permissions?: Record<string, { state?: string }>;
+    supported_surfaces?: string[];
+    matches?: { ref_id?: string }[];
+    value?: string | null;
+    found?: boolean;
   };
+  error?: { code: string; message: string; disposition?: { delivery: string; retry: string } };
+};
 
-  const before = await snapshot("before");
-  const button = unique((before.elements ?? []).filter((e) => e.label === "Increment"), "button");
-  const counter = unique((before.elements ?? []).filter((e) => e.label === "Count"), "counter");
-  if (!button.elementToken || counter.value === undefined) throw new Error("Snapshot lacks the button token or counter value");
-
-  let clicked = false;
-  try {
-    await driver.click(ClickInput.new({
-      target,
-      position: new ClickPosition.Element({ elementToken: button.elementToken }),
-      deliveryMode: InputDeliveryMode.Background,
-      button: ClickButton.Left, count: 1,
-    }));
-    clicked = true;
-  } catch (error) {
-    // A timeout or interrupted action before its response is "unknown": the postcondition below
-    // decides, and the click is never replayed.
-    if (!/timed out|ActionInterrupted/u.test(String(error))) throw error;
-  }
-
-  // Bounded poll on fresh snapshots; never a fixed sleep, never a second click.
-  const deadline = Date.now() + 10_000;
-  let after = await snapshot("after");
-  let updated = unique((after.elements ?? []).filter((e) => e.label === "Count"), "counter");
-  while (updated.value === counter.value && Date.now() < deadline) {
-    await new Promise((resolve) => setTimeout(resolve, 250));
-    after = await snapshot("after");
-    updated = unique((after.elements ?? []).filter((e) => e.label === "Count"), "counter");
-  }
-  if (updated.value !== undefined && updated.value !== counter.value) {
-    finish("verified", `Count ${counter.value} -> ${updated.value}`);
-  } else {
-    finish(clicked ? "refuted" : "unknown", `Count stayed ${counter.value}`);
-  }
-} catch (error) {
-  finish("unknown", String(error));
-} finally {
-  try {
-    await driver.shutdown();
-  } finally {
-    if ("uniffiDestroy" in driver && typeof driver.uniffiDestroy === "function") driver.uniffiDestroy();
-  }
+// On Windows npm's `agent-desktop` command is a .cmd shim that only runs through cmd.exe, which
+// would split an argument at a space and run whatever follows an `&`. Start the native executable
+// the package ships instead, so Node passes every argument literally.
+function agentDesktopCommand(): string {
+  if (process.platform !== "win32") return "agent-desktop";
+  const root = execFileSync("npm", ["root", "-g"], { encoding: "utf8", shell: true }).trim();
+  return join(root, "agent-desktop", "bin", `agent-desktop-win32-${process.arch}.exe`);
 }
-```
 
-The workflow runs a readiness preflight as its own `ctx.tool` first, so a missing permission or session ends the run with `ctx.exit({ status: "blocked", reason })`. A blocked author exit is terminal and not resumable (see [Early exit with `ctx.exit()`](#early-exit-with-ctx-exit)), and the preflight's `{ ready: false }` result is a completed, cached checkpoint, so after the user grants the permission start a new run: its fresh preflight checks again instead of replaying the cached result. The scenario tool spawns `node` with `CUA_DRIVER_RS_TELEMETRY_ENABLED=false` in the child environment, forwards `signal` so a quit or targeted abort kills the child, and maps anything but `verified` to a nonzero outcome:
-
-```ts
-import { spawn } from "node:child_process";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { workflow } from "@bastani/atomic/workflows";
-import { Type } from "typebox";
-
-const sdkDir = join(homedir(), ".cache", "atomic-cua");
-const cuaEnv = { ...process.env, CUA_DRIVER_RS_TELEMETRY_ENABLED: "false" };
-
-function run(command: string, args: string[], signal: AbortSignal, cwd?: string) {
-  return new Promise<{ code: number | null; stdout: string; stderr: string }>((resolve) => {
-    const child = spawn(command, args, { cwd, env: cuaEnv, signal, stdio: ["ignore", "pipe", "pipe"] });
+// One process per command, never through a shell. Every command prints one JSON envelope; branch
+// on `ok`, `error.code` and `disposition`, never on message text.
+function agentDesktop(args: string[], signal: AbortSignal) {
+  return new Promise<Envelope>((resolve) => {
+    const child = spawn(agentDesktopCommand(), args, { signal, stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
     child.stdout.on("data", (chunk: Buffer) => { stdout += chunk.toString(); });
     child.stderr.on("data", (chunk: Buffer) => { stderr += chunk.toString(); });
-    // A missing executable (ENOENT) or an abort arrives here rather than on "close"; treat it as a
+    // A missing executable (ENOENT) or an abort arrives here rather than on "close"; report it as a
     // failed command so the preflight can return its remediation instead of throwing.
-    child.on("error", (error) => resolve({ code: null, stdout, stderr: `${stderr}${error.message}` }));
-    child.on("close", (code) => resolve({ code, stdout, stderr }));
+    child.on("error", (error) =>
+      resolve({ ok: false, error: { code: "SPAWN_FAILED", message: error.message } }));
+    child.on("close", () => {
+      try {
+        resolve(JSON.parse(stdout) as Envelope);
+      } catch {
+        resolve({ ok: false, error: { code: "NO_ENVELOPE", message: stderr.trim() || stdout.trim() } });
+      }
+    });
   });
 }
 
 export default workflow({
   name: "verify-counter",
   description: "Prove the Increment button changes the Count field in the Counter window.",
-  inputs: { artifactsDir: Type.String({ description: "Directory for before/after state JSON and screenshots" }) },
+  inputs: { artifactsDir: Type.String({ description: "Directory for before/after screenshots" }) },
   outputs: { result: Type.String(), detail: Type.String() },
   run: async (ctx) => {
     const preflight = await ctx.tool(
-      "cua-preflight",
+      "agent-desktop-preflight",
       { platform: process.platform },
       async ({ signal }) => {
-        const version = await run("cua-driver", ["--version"], signal);
-        if (version.code !== 0) {
-          return { ready: false, reason: "cua-driver is not installed; run /bin/bash -c \"$(curl -fsSL https://cua.ai/driver/install.sh)\" (Windows: irm https://cua.ai/driver/install.ps1 | iex), then cua-driver telemetry disable" };
+        const version = await agentDesktop(["version"], signal);
+        if (!version.ok) {
+          return { ready: false, reason: "agent-desktop is not installed or not on PATH; run `npm install -g agent-desktop` (approve its install script if npm blocks it), then `agent-desktop version`" };
         }
-        const status = await run("cua-driver", ["status"], signal);
-        const daemon = status.code === 0;
-        if (process.platform === "darwin" && daemon) {
-          const permissions = await run("cua-driver", ["permissions", "status", "--json"], signal);
-          const grants = permissions.code === 0
-            ? (JSON.parse(permissions.stdout) as { accessibility?: boolean; screen_recording?: boolean })
-            : {};
-          if (grants.accessibility !== true || grants.screen_recording !== true) {
-            return { ready: false, reason: "Missing macOS grant: run `cua-driver permissions grant`, toggle CuaDriver on under System Settings → Privacy & Security → Accessibility and Screen & System Audio Recording, then relaunch the daemon with `open -n -g -a CuaDriver --args serve`" };
+        const status = await agentDesktop(["status"], signal);
+        if (!status.ok) {
+          return { ready: false, reason: `agent-desktop status failed: ${status.error?.message ?? "no envelope"}` };
+        }
+        const permissions = status.data?.permissions ?? {};
+        for (const name of ["accessibility", "screen_recording"] as const) {
+          const state = permissions[name]?.state;
+          if (state !== "granted" && state !== "not_required") {
+            return { ready: false, reason: `Missing ${name} permission (${state}): run \`agent-desktop permissions --guide\` and have the user grant it to the app that launches the command` };
           }
         }
-        const apps = await run("cua-driver", ["call", "list_apps"], signal);
-        if (apps.code !== 0) {
-          return { ready: false, reason: `cua-driver call list_apps failed; start the daemon (macOS: open -n -g -a CuaDriver --args serve; Windows: cua-driver serve in the interactive session; Linux: cua-driver serve inside the graphical session): ${apps.stderr.trim()}` };
+        if (!status.data?.supported_surfaces?.length) {
+          return { ready: false, reason: "No readable surfaces: run inside the user's graphical session with a running AT-SPI bus, then rerun `agent-desktop status`" };
         }
-        return { ready: true, daemon };
+        return { ready: true };
       },
       { timeoutMs: 60_000 },
     );
@@ -691,17 +618,54 @@ export default workflow({
 
     const scenario = await ctx.tool(
       "verify-counter-scenario",
-      { artifactsDir: ctx.inputs.artifactsDir, daemon: preflight.daemon },
+      { artifactsDir: ctx.inputs.artifactsDir },
       async ({ signal }) => {
-        const args = JSON.stringify({ daemon: preflight.daemon, artifactsDir: ctx.inputs.artifactsDir });
-        const child = await run("node", ["verify-counter.mjs", args], signal, sdkDir);
-        const line = child.stdout.trim().split("\n").at(-1) ?? "";
-        const parsed = line.startsWith("{") ? (JSON.parse(line) as { result: string; detail: string }) : undefined;
-        const result = parsed?.result ?? "unknown";
-        if (result !== "verified") {
-          throw new Error(`desktop verification ${result}: ${parsed?.detail ?? child.stderr.trim()}`);
+        // Replace the app name, element names, and postcondition with ones you control.
+        const app = "Window Demo";
+        mkdirSync(ctx.inputs.artifactsDir, { recursive: true });
+        // Keep every result as evidence beside the screenshots, and fail rather than report
+        // `verified` when a piece of evidence is missing.
+        const save = (step: string, envelope: Envelope) => {
+          writeFileSync(join(ctx.inputs.artifactsDir, `${step}.json`), JSON.stringify(envelope, null, 2));
+          return envelope;
+        };
+        const capture = async (step: string) => {
+          const shot = save(step, await agentDesktop(["screenshot", "--app", app, join(ctx.inputs.artifactsDir, `${step}.png`)], signal));
+          if (!shot.ok) throw new Error(`Could not capture the ${step} screenshot: ${shot.error?.code ?? "no envelope"}`);
+        };
+        const one = async (role: string, name: string) => {
+          const found = await agentDesktop(["find", "--app", app, "--role", role, "--name", name, "--exact", "--limit", "2"], signal);
+          const matches = found.data?.matches ?? [];
+          if (!found.ok || matches.length !== 1 || !matches[0].ref_id) {
+            throw new Error(`Expected one ${role} named ${name}: ${found.error?.code ?? `${matches.length} matches`}`);
+          }
+          return matches[0].ref_id;
+        };
+
+        const button = await one("button", "Increment");
+        const field = await one("textfield", "Count");
+        const read = save("read-before", await agentDesktop(["get", field, "--property", "value"], signal));
+        const before = Number(read.data?.value);
+        if (!read.ok || Number.isNaN(before)) throw new Error("Count has no numeric value to start from");
+        await capture("before");
+
+        // Act once. An error whose disposition is `retry: "safe"` changed nothing, so the node fails
+        // and a new run starts fresh; any other failure may have landed, so the wait below decides.
+        const click = save("click", await agentDesktop(["click", button], signal));
+        const notDelivered = click.error?.disposition?.retry === "safe";
+        if (!click.ok && notDelivered) throw new Error(`Click was not delivered: ${click.error?.code}`);
+
+        // Verify with a bounded wait on the postcondition, never a sleep and never a second click.
+        const expected = String(before + 1);
+        const waited = save("wait", await agentDesktop(["wait", "--element", field, "--predicate", "value", "--value", expected, "--timeout", "10000"], signal));
+        await capture("after");
+        if (waited.ok && waited.data?.found) {
+          return { result: "verified", detail: `Count ${before} -> ${expected}; evidence in ${ctx.inputs.artifactsDir}` };
         }
-        return { result, detail: parsed?.detail ?? "" };
+        // A click that errored without a safe disposition, or a wait that timed out, is not proof
+        // either way: report it as unknown or refuted and let the next run start from fresh state.
+        const result = click.ok ? "refuted" : "unknown";
+        throw new Error(`desktop verification ${result}: Count did not become ${expected} (${waited.error?.code ?? "no match"})`);
       },
       { timeoutMs: 5 * 60_000 },
     );
@@ -711,7 +675,7 @@ export default workflow({
 });
 ```
 
-A `verified` result is cached durably, so a resumed run does not click again. A thrown `refuted`, `blocked`, or `unknown` result fails the node and is not replayed from cache; a new run executes the preflight and the scenario again from a fresh snapshot, and a durable retry of a resumable failure replays the completed preflight checkpoint and re-runs only the scenario. Keep the artifacts directory outside the repository unless the evidence belongs in the deliverable, and never post the installation UUID from `cua-driver telemetry status` in a result or reason. Safety is the same on both faces: one controller per desktop, a dedicated session or account where practical, and an explicit stopping point before destructive or publishing actions.
+A `verified` result is cached durably, so a resumed run does not click again. A thrown `refuted` or `unknown` result fails the node and is not replayed from cache; a new run executes the preflight and the scenario again from fresh refs, and a durable retry of a resumable failure replays the completed preflight checkpoint and re-runs only the scenario. Refs belong to the snapshot that produced them, so look an element up again after any UI change instead of reusing a ref from an earlier step. Keep the artifacts directory outside the repository unless the evidence belongs in the deliverable. Safety is the same on both paths: one controller per desktop, a dedicated session or account where practical, and an explicit stopping point before destructive or publishing actions.
 
 ### Classifier and image models in `ctx.tool`
 

package/docs/workflows/verification.md

@@ -2,7 +2,7 @@
 
 Verify the behavior that changed, then give the reviewer enough evidence to understand the result. A small fix may need a focused test and a short explanation. An interactive change usually needs a real user scenario as well. A video is useful when it shows something a test log or screenshot cannot; it is not required for every PR.
 
-For tool installation, automation techniques, platform permissions, and general work in applications, read [Computer use](/computer-use). That guide covers Herdr for terminals, agent-browser for browsers, Mobile Safari, and CDP-exposing apps, and Cua Driver for other desktop, simulator, and emulator CUA on macOS, Linux, and Windows. It also covers native accessibility and application tools when they are easier or more reliable.
+For tool installation, automation techniques, platform permissions, and general work in applications, read [Computer use](/computer-use). That guide covers Herdr for terminals, agent-browser for browsers, Mobile Safari, and CDP-exposing apps, and agent-desktop for native desktop apps and OS dialogs on macOS, Linux, and Windows. It also covers native accessibility and application tools when they are easier or more reliable.
 
 <a id="select-the-verification-environment" />
 
@@ -13,12 +13,13 @@ Start with the project's existing tests, build, typecheck, and lint commands. Ad
 | Changed behavior | Preferred mechanism | What to check |
 | --- | --- | --- |
 | Interactive terminal or TUI | **Herdr**, under its explicit-request and managed-pane requirements; tmux or native Windows psmux as fallbacks | Actual input, rendered output, navigation, resizing, and exit behavior relevant to the change. |
-| Browser/frontend in Chrome/Chromium, Mobile Safari in the iOS Simulator, Electron desktop app or another CDP-exposing app, Slack, or cloud browser | **agent-browser**, for everything in [its scope](/computer-use#what-agent-browser-covers); Cua Driver when agent-browser hits a limitation | The user flow and its visible result, with DOM or network assertions where useful. |
-| Native desktop app, native iOS app in the iOS Simulator, Android emulator, desktop Safari or another non-Chromium browser, or OS dialogs | **Cua Driver**: the `cua-driver` CLI through the bundled skill when a model chooses actions, or the `@trycua/cua-driver` SDK inside `ctx.tool` when workflow code owns the scenario; supplemented by native/app APIs | The exact window's before/after accessibility state and screenshots, a checked postcondition, and the saved or exported result. |
+| Browser/frontend in Chrome/Chromium, Mobile Safari in the iOS Simulator, Electron desktop app or another CDP-exposing app, Slack, or cloud browser | **agent-browser**, for everything in [its scope](/computer-use#what-agent-browser-covers); agent-desktop when agent-browser hits a limitation | The user flow and its visible result, with DOM or network assertions where useful. |
+| Native desktop app, menus and menu bars, desktop Safari or another non-Chromium browser, or OS dialogs and permission prompts | **agent-desktop**: the bundled `agent-desktop` skill and one-shot `agent-desktop` commands when a model chooses actions, or the `agent-desktop` CLI called from `ctx.tool` when workflow code owns the scenario; supplemented by native/app APIs | The exact app's before/after accessibility state from the JSON results, screenshots, a checked postcondition, and the saved or exported result. |
+| Native iOS app in the Simulator or Android app in an emulator | **Native mobile tooling**: `xcrun simctl`, Appium with XCUITest, or `adb` with UI Automator. agent-desktop sees a simulator or emulator only as a desktop window ([coverage and limits](/computer-use#coverage-and-limits)) | The device or emulator actually exercised, its screenshots or recording, and the checked postcondition. |
 | API, library, script, or other non-UI behavior | Existing test runner and shell commands | Inputs, outputs, error handling, and relevant build/type contracts. |
 | Documentation | Documentation checks and example review | Links, navigation, command accuracy, and whether a reader can follow the instructions. |
 
-See [tool selection](/computer-use#choose-the-right-tool) before operating a session. Reach for agent-browser first whenever the target is in its scope: its text snapshots cost far fewer tokens than screenshot-driven CUA. Herdr is the terminal priority, but the preference does not authorize control from outside a Herdr-managed pane. Install missing tools when permitted; otherwise use the available fallback and describe any coverage gap.
+See [tool selection](/computer-use#choose-the-right-tool) before operating a session. Reach for agent-browser first whenever the target is in its scope: its text snapshots cost far fewer tokens than desktop accessibility trees and screenshots. Herdr is the terminal priority, but the preference does not authorize control from outside a Herdr-managed pane. Install missing tools when permitted; otherwise use the available fallback and describe any coverage gap.
 
 ### Reuse past verification
 
@@ -26,7 +27,7 @@ When a shell tool is available, the agent records each check it ran or attempted
 
 ```text
 Assistant-verification: herdr terminal E2E passed: /tasks lists running tasks first at 80x24
-Assistant-verification: cua-driver unavailable: Accessibility permission not granted
+Assistant-verification: agent-desktop unavailable: Accessibility permission not granted
 ```
 
 Before choosing checks for a change, the agent looks up these lines for comparable changes (for example with `git log --format='%h %s%n%(trailers:key=Assistant-verification)' -- <path>`) and reuses the commands and scenarios that proved them. A setup recorded as `unavailable` is not retried without a reason to expect a different result. Past records guide the choice; they do not replace the project's required checks. See [execution history](/usage#system-prompt-files) to turn these records off.
@@ -99,19 +100,19 @@ See [terminal setup and capture commands](/computer-use#terminal-automation-with
 
 <a id="desktop-safety" />
 
-### Native desktop, simulator, and emulator changes
+### Native desktop changes
 
-Use Cua Driver in a dedicated graphical session, following [the desktop guide](/computer-use#desktop-automation-with-cua-driver). When a language model chooses each action, whether in an interactive session or in any workflow stage acting outside `ctx.tool`, load the bundled `cua-driver` skill and drive the exact window with one-shot `cua-driver call <tool>` commands, running every command with `CUA_DRIVER_RS_TELEMETRY_ENABLED=false`. When a custom workflow's TypeScript owns the scenario and its postcondition, run it with the `@trycua/cua-driver` SDK inside `ctx.tool` as shown in [workflow authoring](/workflows/authoring#desktop-verification-with-cua-driver-in-ctx-tool). Either way the loop is the same: snapshot the window with `get_window_state`, act through a snapshot-bound element token, take a fresh snapshot, and check a postcondition with a bounded poll deadline. Application APIs can still give the strongest assertion, for example checking a saved document through the app API after exercising the visible Save flow.
+Use agent-desktop in a dedicated graphical session, following [the desktop guide](/computer-use#desktop-automation-with-agent-desktop). When a language model chooses each action, whether in an interactive session or in any workflow stage acting outside `ctx.tool`, load the bundled `agent-desktop` skill, read `agent-desktop skills get desktop` and `agent-desktop skills get platform`, and drive the app with one-shot `agent-desktop` commands. When a custom workflow's TypeScript owns the scenario and its postcondition, call the `agent-desktop` CLI from `ctx.tool` as shown in [workflow authoring](/workflows/authoring#desktop-verification-with-agent-desktop-in-ctx-tool). Either way the loop is the same: snapshot the app, act on a ref from that snapshot, then `wait` for the postcondition with a bounded timeout and read it back. Application APIs can still give the strongest assertion, for example checking a saved document through the app API after exercising the visible Save flow.
 
-Evidence is the structured window state plus screenshots, not a screenshot alone. Save each `get_window_state` JSON result and its `screenshot_out_file` image (before and after the action) to the artifacts directory, and state the postcondition that was checked. A `degraded` or `truncated` snapshot is a failed observation, not a reason to act.
+Evidence is the structured accessibility state plus screenshots, not a screenshot alone. Save the JSON results of the snapshot, the action and the `wait` that verified it, and an `agent-desktop screenshot` before and after the action, to the artifacts directory, and state the postcondition that was checked. A snapshot whose `data.complete` is `false` is a partial observation: drill further before acting. An action result is not proof that the UI changed; only the read that follows is.
 
-Capture the actual application or simulator. A Chrome recording is not desktop or native iOS evidence, and an agent-browser `-p ios` session proves Mobile Safari behavior, not a native iOS app. Cua Driver can interact with a visible simulator/emulator window, but does not directly control an arbitrary physical phone. Use supported native tooling where needed, and name the device or emulator actually exercised.
+Capture the actual application. A Chrome recording is not desktop or native iOS evidence, and an agent-browser `-p ios` session proves Mobile Safari behavior, not a native iOS app. agent-desktop sees an iOS Simulator or Android emulator only as a desktop window and may not see the simulated device's UI, so use native mobile tooling (`xcrun simctl`, Appium with XCUITest, or `adb` with UI Automator) for native mobile apps, and name the device or emulator actually exercised. If none is available, report the gap instead of claiming coverage.
 
-Missing readiness is a blocked finding, not a failure to work around. Before the first action the stage checks `cua-driver --version` (one bounded install attempt with upstream's one-line installer if it is missing, then `cua-driver telemetry disable`), `cua-driver status`, `cua-driver doctor`, and `cua-driver call list_apps`, plus `cua-driver permissions status` on macOS. A builtin Goal or Ralph stage reports a missing macOS Accessibility or Screen Recording grant, a non-interactive Windows session, no graphical Linux session, or a refused or failed install as `blocked`/`needs_human` with the exact remediation (for macOS: `cua-driver permissions grant`, toggle CuaDriver on under System Settings → Privacy & Security → Accessibility and Screen & System Audio Recording, then relaunch the daemon with `open -n -g -a CuaDriver --args serve`), and re-runs the readiness check when the run resumes. A custom workflow does the same from a preflight `ctx.tool` that calls `ctx.exit({ status: "blocked", reason })`. Unlike a builtin stage, a blocked author exit is terminal and not resumable: after the user grants the permission, start a new run, whose fresh preflight checks again rather than replaying a cached result.
+Missing readiness is a blocked finding, not a failure to work around. Before the first action the stage checks `agent-desktop version` (one bounded `npm install -g agent-desktop` attempt if it is missing, approving the package's install script when npm blocks it) and `agent-desktop status`. A builtin Goal or Ralph stage reports a missing macOS Accessibility permission (or Screen Recording when it needs screenshots), a non-interactive Windows session, no graphical Linux session with a running AT-SPI bus (an empty `supported_surfaces`), or a refused or failed install as `blocked`/`needs_human` with the exact remediation (for macOS: `agent-desktop permissions --guide`, then grant the terminal or editor that launches the command), and re-runs `agent-desktop status` when the run resumes. A custom workflow does the same from a preflight `ctx.tool` that calls `ctx.exit({ status: "blocked", reason })`. Unlike a builtin stage, a blocked author exit is terminal and not resumable: after the user grants the permission, start a new run, whose fresh preflight checks again rather than replaying a cached result.
 
-The executable installer does not install an agent skill. Atomic bundles the skill, so skip upstream's optional `cua-driver skills install`, `cua-driver skills update`, and `clawhub install @cua/driver` steps; leave existing user-level skills alone.
+Atomic bundles the `agent-desktop` skill, so skip `npx skills add` for it, and leave existing user-level skills alone. The detailed guides come from the installed CLI (`agent-desktop skills get ...`), so they always match its version.
 
-Inspect saved files and exports rather than assuming a returned action means a completed operation. An action that times out before its response is `unknown`; resolve it with a fresh snapshot and the postcondition, never by replaying the action.
+Inspect saved files and exports rather than assuming a returned action means a completed operation. Retry or substitute an action only when its `disposition.retry` is `safe`. An action that times out before its response, or whose delivery is anything but `not_delivered`, is `unknown`; resolve it with a fresh read and the postcondition, never by replaying the action.
 
 ## Use evidence in a workflow
 
@@ -156,7 +157,7 @@ Give the reviewer a short summary before linking logs or media. For example, rep
 - Limits: <checks/platforms not exercised>
 ```
 
-Attach a screenshot for a visual state, a short recording for an interaction, or logs for command behavior. When a run used Cua Driver, the evidence is the before/after `screenshot_out_file` PNGs from `get_window_state`, one pair per verified postcondition, with the window-state JSON kept locally and cited by name; when it used agent-browser, the evidence is its `screenshot` PNGs and `record` recordings (for an iOS Simulator session, its screenshots plus any `simctl` recording). Put them in the PR body next to the scenario they prove. Include reproduction steps even when media is available. Label local-only paths as local; reviewers cannot open a file on your machine. CI artifact links are useful when readers have access, but note retention limits where relevant.
+Attach a screenshot for a visual state, a short recording for an interaction, or logs for command behavior. When a run used agent-desktop, the evidence is the before/after `agent-desktop screenshot` PNGs, one pair per verified postcondition, with the snapshot, action and `wait` JSON kept locally and cited by name; when it used agent-browser, the evidence is its `screenshot` PNGs and `record` recordings (for an iOS Simulator session, its screenshots plus any `simctl` recording). Put them in the PR body next to the scenario they prove. Include reproduction steps even when media is available. Label local-only paths as local; reviewers cannot open a file on your machine. CI artifact links are useful when readers have access, but note retention limits where relevant.
 
 Only upload to an authorized repository or destination. Inspect and redact secrets, personal information, private source content, and unrelated windows before attaching files. Permission to collect local evidence is not permission to publish it.
 

package/npm-shrinkwrap.json

@@ -1,16 +1,16 @@
 {
 	"name": "@bastani/atomic",
-	"version": "0.9.56-alpha.1",
+	"version": "0.9.57-alpha.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@bastani/atomic",
-			"version": "0.9.56-alpha.1",
+			"version": "0.9.57-alpha.1",
 			"license": "MIT",
 			"dependencies": {
-				"@bastani/atomic-natives": "0.9.56-alpha.1",
-				"@bastani/pi-ai": "0.9.56-alpha.1",
+				"@bastani/atomic-natives": "0.9.57-alpha.1",
+				"@bastani/pi-ai": "0.9.57-alpha.1",
 				"@earendil-works/pi-agent-core": "1.4.0",
 				"@earendil-works/pi-codemode": "1.4.0",
 				"@earendil-works/pi-tui": "1.4.0",
@@ -427,18 +427,18 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives": {
-			"version": "0.9.56-alpha.1",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.56-alpha.1.tgz",
+			"version": "0.9.57-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.57-alpha.1.tgz",
 			"license": "MIT",
 			"optionalDependencies": {
-				"@bastani/atomic-natives-darwin-arm64": "0.9.56-alpha.1",
-				"@bastani/atomic-natives-darwin-x64": "0.9.56-alpha.1",
-				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.56-alpha.1",
-				"@bastani/atomic-natives-linux-arm64-musl": "0.9.56-alpha.1",
-				"@bastani/atomic-natives-linux-x64-gnu": "0.9.56-alpha.1",
-				"@bastani/atomic-natives-linux-x64-musl": "0.9.56-alpha.1",
-				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.56-alpha.1",
-				"@bastani/atomic-natives-win32-x64-msvc": "0.9.56-alpha.1"
+				"@bastani/atomic-natives-darwin-arm64": "0.9.57-alpha.1",
+				"@bastani/atomic-natives-darwin-x64": "0.9.57-alpha.1",
+				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.57-alpha.1",
+				"@bastani/atomic-natives-linux-arm64-musl": "0.9.57-alpha.1",
+				"@bastani/atomic-natives-linux-x64-gnu": "0.9.57-alpha.1",
+				"@bastani/atomic-natives-linux-x64-musl": "0.9.57-alpha.1",
+				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.57-alpha.1",
+				"@bastani/atomic-natives-win32-x64-msvc": "0.9.57-alpha.1"
 			},
 			"engines": {
 				"bun": ">=1.4.2",
@@ -446,8 +446,8 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives-darwin-arm64": {
-			"version": "0.9.56-alpha.1",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.56-alpha.1.tgz",
+			"version": "0.9.57-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.57-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -458,8 +458,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-darwin-x64": {
-			"version": "0.9.56-alpha.1",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.56-alpha.1.tgz",
+			"version": "0.9.57-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.57-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -470,8 +470,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-arm64-gnu": {
-			"version": "0.9.56-alpha.1",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.56-alpha.1.tgz",
+			"version": "0.9.57-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.57-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -485,8 +485,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-arm64-musl": {
-			"version": "0.9.56-alpha.1",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-musl/-/atomic-natives-linux-arm64-musl-0.9.56-alpha.1.tgz",
+			"version": "0.9.57-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-musl/-/atomic-natives-linux-arm64-musl-0.9.57-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -500,8 +500,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-x64-gnu": {
-			"version": "0.9.56-alpha.1",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.56-alpha.1.tgz",
+			"version": "0.9.57-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.57-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -515,8 +515,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-x64-musl": {
-			"version": "0.9.56-alpha.1",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-musl/-/atomic-natives-linux-x64-musl-0.9.56-alpha.1.tgz",
+			"version": "0.9.57-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-musl/-/atomic-natives-linux-x64-musl-0.9.57-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -530,8 +530,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-arm64-msvc": {
-			"version": "0.9.56-alpha.1",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.56-alpha.1.tgz",
+			"version": "0.9.57-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.57-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"
@@ -542,8 +542,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-x64-msvc": {
-			"version": "0.9.56-alpha.1",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.56-alpha.1.tgz",
+			"version": "0.9.57-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.57-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"
@@ -554,8 +554,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/pi-ai": {
-			"version": "0.9.56-alpha.1",
-			"resolved": "https://registry.npmjs.org/@bastani/pi-ai/-/pi-ai-0.9.56-alpha.1.tgz",
+			"version": "0.9.57-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/pi-ai/-/pi-ai-0.9.57-alpha.1.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"@anthropic-ai/sdk": "0.129.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.9.56-alpha.1",
+  "version": "0.9.57-alpha.1",
   "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "atomicConfig": {
@@ -89,8 +89,8 @@
     "prepublishOnly": "bun run clean && bun run build && bun run shrinkwrap"
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.9.56-alpha.1",
-    "@bastani/pi-ai": "0.9.56-alpha.1",
+    "@bastani/atomic-natives": "0.9.57-alpha.1",
+    "@bastani/pi-ai": "0.9.57-alpha.1",
     "@earendil-works/pi-agent-core": "1.4.0",
     "@earendil-works/pi-codemode": "1.4.0",
     "@earendil-works/pi-tui": "1.4.0",