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

package/dist/builtin/subagents/skills/cua-driver/EMBEDDING.md

@@ -1,685 +0,0 @@
-# Embedding cua-driver in your application without introducing new permissions
-
-This guide is for teams shipping a macOS app (an "agent harness") that wants
-cua-driver's background computer-use and agent-cursor overlay **inside their
-own app**, without shipping a second app bundle and without their users ever
-seeing a second macOS permission prompt. Your app requests Accessibility and
-Screen Recording once; the embedded driver inherits those grants.
-
-A working daemon-host reference lives in the cua repo at
-`libs/cua-driver/rust/examples/embedded-host-macos/`
-(https://github.com/trycua/cua). This doc ships standalone in the skill
-pack, so the path is given rather than a relative link.
-
-## How macOS attributes these permissions (what you must know)
-
-macOS TCC (the privacy system behind System Settings → Privacy & Security)
-does not attribute Accessibility or Screen Recording to an executable path.
-It attributes them to the **responsible process**: the app at the top of the
-process's launch chain, as tracked by the kernel/LaunchServices. When your
-signed app spawns a child with `posix_spawn`, `NSTask`/`Process`, or plain
-`fork`/`exec`, that child stays inside _your_ responsibility chain: TCC
-checks made by the child are answered with **your app's** grants, and any
-prompt it triggered would name **your app**. This is exactly the behavior
-embedding relies on: grant once to the host, and every well-behaved child
-inherits. (Apple documents the attribution chain; you can watch it live with
-`log stream --debug --predicate 'subsystem == "com.apple.TCC" AND eventMessage BEGINSWITH "AttributionChain"'`.)
-
-Two things break the chain, and both are things the embedded driver must
-_not_ do (and, in embedded mode, does not do). First, launching via
-LaunchServices (`open -a …`, `NSWorkspace.open`) makes the launched app its
-own responsible process. Second, a process can explicitly _disclaim_
-responsibility for a child (`responsibility_spawnattrs_setdisclaim`), making
-the child its own responsible process: standalone cua-driver does this on
-purpose so its permissions attach to a stable `com.trycua.driver` identity
-instead of whatever terminal launched it. Embedded mode turns that off.
-
-Note this is TCC **responsibility** inheritance: it is unrelated to App
-Sandbox inheritance (`com.apple.security.inherit`). This guide assumes a
-non-sandboxed host, which is typical for agent harnesses; a sandboxed host
-spawning a non-sandboxed helper raises separate App Sandbox questions that
-embedded mode does not address.
-
-## Preferred application SDK: same-process runtime
-
-Python and TypeScript applications should normally import the packaged SDK and
-create `CuaDriver` directly. This path does not start an executable or open a
-socket, and TCC checks execute as the importing application:
-
-```ts
-import { CuaDriver } from '@trycua/cua-driver';
-
-const driver = CuaDriver.create(undefined);
-try {
-  const metadata = await driver.metadata();
-  // Invoke typed driver operations here.
-} finally {
-  await driver.shutdown();
-  driver.uniffiDestroy();
-}
-```
-
-The direct runtime never presents macOS permission UI. Even
-`check_permissions({prompt: true})` is forced into a read-only check and
-reports the host as the responsible permission owner. After the host changes
-Accessibility or Screen Recording grants, fully relaunch the host before
-creating a replacement runtime.
-
-The AppKit agent-cursor overlay is not available in an arbitrary direct
-runtime. Until a host installs a certified main-thread UI adapter, overlay
-methods return structured `facility_unavailable` results. Use the private
-worker or daemon-backed host when the visible overlay is required.
-
-Use the daemon-backed host below only when the application must also provide a
-stable MCP endpoint to an external agent, coordinate external clients, or keep
-the automation runtime isolated from the application process.
-
-## Launching the daemon-backed host
-
-```sh
-# env var form: set by the host on the child process
-CUA_DRIVER_EMBEDDED=1 CUA_DRIVER_HOST_BUNDLE_ID=com.yourco.yourapp \
-  cua-driver serve --socket /tmp/yourapp-cua.sock
-
-# after the daemon socket is ready, start the stdio MCP proxy
-CUA_DRIVER_EMBEDDED=1 cua-driver mcp --socket /tmp/yourapp-cua.sock
-```
-
-Requirements on the host side:
-
-- **Spawn `cua-driver serve --embedded` directly** as a child process
-  (`Process`/`NSTask`, `posix_spawn`, `exec` from your own code). Do
-  **not** launch the daemon via `open(1)` or `NSWorkspace`: that hands it
-  to LaunchServices and breaks inheritance.
-- Give the daemon a private socket and wait until it is accepting connections.
-- Spawn `cua-driver mcp --embedded --socket <path>` and speak MCP over that
-  proxy's stdin/stdout (line-delimited JSON-RPC). The proxy never executes
-  tools; the host-owned daemon does.
-- Request Accessibility and Screen Recording **from your app** before (or
-  after: the driver just reports "not granted" until then) starting the
-  driver, using `AXIsProcessTrustedWithOptions([kAXTrustedCheckOptionPrompt: true])`
-  and `CGRequestScreenCaptureAccess()`.
-
-Only the exact value `CUA_DRIVER_EMBEDDED=1` enables embedded mode; anything
-else is ignored (fail-safe). `--host-bundle-id` is an advisory label echoed
-in `check_permissions` output and logs: it is **not** a trust signal; trust
-comes from the OS responsibility chain, so there is nothing to spoof by
-setting it.
-
-## Choosing the agent permission mode
-
-Embedded hosts own their user-facing permission experience, but they must
-select Cua Driver's immutable runtime mode at trusted launch. The choices are:
-
-- `standard`: promptless routine automation, with explicit host authorization
-  only for residual boundaries such as an existing logged-in Chromium profile.
-- `bounded`: unattended work inside an approved tool and resource manifest.
-- `unrestricted`: no Cua runtime approvals; use only when the host accepts the
-  consequences of prompt injection and unintended actions.
-
-Direct SDK hosts may install `DriverAuthorizationHost` for residual
-standard-mode decisions and `DriverActivityObserver` for content-free action
-events. Cua Driver does not render its own authorization modal or banner.
-
-For unrestricted embedding, use the explicit two-part environment contract:
-
-```sh
-CUA_DRIVER_EMBEDDED=1 \
-CUA_DRIVER_PERMISSION_MODE=unrestricted \
-CUA_DRIVER_DANGEROUSLY_BYPASS_APPROVALS=1 \
-  cua-driver serve --embedded --socket /tmp/yourapp-cua.sock
-```
-
-Both values are required and contradictory values fail before the daemon
-binds. They belong in trusted launcher configuration; never expose either as
-an agent-settable MCP or raw-socket argument. Interactive operators can use
-the equivalent single CLI shortcut, `--dangerously-bypass-approvals`, which
-selects unrestricted mode and records the acknowledgement. The older
-`autonomous` mode name remains accepted as an alias for `bounded` during
-migration.
-
-### Node and Electron daemon hosts
-
-Use the embedded host in `@trycua/cua-driver` instead of implementing process
-and socket management in every host. It starts a private daemon directly, waits
-until its socket accepts connections, returns SDK and MCP connection details,
-and owns restart and cleanup:
-
-```ts
-import { CuaDriver, EmbeddedCuaDriverHost } from '@trycua/cua-driver';
-
-const embedded = new EmbeddedCuaDriverHost(
-  '/path/inside/YourApp.app/Contents/Resources/cua-driver',
-  'com.example.your-app'
-);
-const connection = await embedded.start();
-const driver = CuaDriver.connect(connection.socketPath);
-// Application calls use driver; an agent runtime uses connection.mcp.
-driver.uniffiDestroy();
-await embedded.stop();
-embedded.uniffiDestroy();
-```
-
-The package does not install or bundle cua-driver. Ship a compatible executable
-outside Electron's ASAR archive, preserve its executable bit, and sign the
-nested executable before signing and notarizing the enclosing macOS app.
-Electron main processes can use the package's `/electron` entry point for
-low-level Accessibility and Screen Recording requests after `app.whenReady()`;
-the calls run as the importing host, not the child driver. The host still owns
-permission UI, status, and restart policy. These functions use the same
-generated Rust SDK; there is no second native FFI dependency. Some macOS
-releases refuse to raise a Screen Recording prompt; in that case, open the
-Screen Recording settings pane with
-`openMacOSScreenRecordingSettings()`, ask the user to add the host app, and
-start the driver only after both checks return true.
-
-Destroy the SDK client and call `await embedded.stop()` from every orderly
-shutdown path. If grants change, destroy the SDK client, call
-`embedded.restart()`, and reconnect. Electron hosts must defer their first
-`before-quit` event until cleanup completes because asynchronous cleanup cannot
-run after the host process exits. Normal OpenClaw
-gateway and Hermes YAML configurations remain standalone integrations; use the
-package only when their signed Node or Electron app process directly owns the
-daemon child.
-
-### Lifecycle rules
-
-- Concurrent `start()` calls coalesce into one daemon generation.
-- Treat `connection` as generation-scoped. After `restart()`, destroy old SDK
-  clients and MCP proxies and reconnect from the newly returned descriptor.
-- Stop new work, end sessions, close proxies/clients, then await `stop()`.
-  `stop()` is idempotent and cancels an in-progress start.
-- Observe unexpected termination with `waitForExit(generation)` in Node or
-  `wait_for_exit(generation)` in Python. Never blindly replay an action whose
-  completion is unknown.
-- The Rust owner holds a parent-liveness pipe, so host death closes the daemon;
-  orderly shutdown should still await `stop()`.
-- Capture modality belongs to each observation or action target, not to the
-  lifecycle session. One embedded daemon can concurrently serve exact window
-  and desktop calls without changing session state.
-- Permission changes require destroying clients, restarting the daemon, and
-  reconnecting. A connection from the old generation is never reusable.
-
-## Bounding the post-action window observation
-
-After an input action, the driver watches the window list for a short time so
-it can report a menu, dialog, or new window that the action opened. On macOS,
-the watch lasts up to 1000 ms. The action's result waits for at most the first
-300 ms of it; when nothing has changed by then, the result returns and the rest
-of the watch runs detached, still holding the focus-steal lease. A window that
-opens during that remainder is reported on the next action's result as
-`After the previous action returned, it opened new window(s): …`. The next
-action, or any activation the driver performs, ends the detached remainder
-first. On Linux X11 the result waits for the whole watch. A host that already observes
-its target continuously can shorten it through two variables set at trusted
-launch, in the environment of the `serve --embedded` child (or of the host
-process when you use the same-process runtime). `EmbeddedCuaDriverHost` starts
-that child from an allowlisted environment that admits both variables, so pass
-them in its `environment` option or set them in the host process:
-
-| Variable                              | Meaning                                              | Default                         | Accepted range                            |
-| ------------------------------------- | ---------------------------------------------------- | ------------------------------- | ----------------------------------------- |
-| `CUA_DRIVER_WINDOW_CHANGE_TIMEOUT_MS` | Longest wait for a window change after each action.  | 1000 on macOS, 800 on Linux X11 | 0 to 10000; larger values are clamped     |
-| `CUA_DRIVER_WINDOW_CHANGE_POLL_MS`    | Interval between window-list reads during that wait. | 50                              | 5 to 1000, and never longer than the wait |
-
-Unset, empty, or unparsable values, such as `-1`, `1.5`, or `100ms`, keep the
-default, so a daemon launched without these variables behaves exactly as
-before. No tool argument can change the bound. Every ingress strips
-underscore-prefixed arguments, so an agent cannot shorten its own focus
-protection.
-
-```sh
-CUA_DRIVER_EMBEDDED=1 \
-CUA_DRIVER_WINDOW_CHANGE_TIMEOUT_MS=200 \
-  cua-driver serve --embedded --socket /tmp/yourapp-cua.sock
-```
-
-A shorter wait costs something on each platform. Choose a value knowingly.
-
-- **macOS: less focus protection.** The watch also holds a focus-steal lease:
-  while it runs, the driver reactivates the app that was frontmost before the
-  action if any other app activates, such as a browser opened by a link. The
-  lease ends when the watch ends. With a nonzero value, cross-app activations
-  are reverted only for that long after the action returns. With `0`, the lease
-  is released as soon as the action returns. The separate target-pid guard
-  remains, and it still covers the action plus a 50 ms settle when the target
-  was not frontmost. An app that activates later stays frontmost, so the host
-  must detect and correct that itself.
-- **macOS: missing result suffixes.** A window that appears after the wait
-  ends is not reported. With `0`, results never carry
-  `Action opened new window(s): …` or
-  `Action caused a different app to become frontmost.`
-- **Linux X11 foreground delivery: weaker evidence.** A foreground-delivery
-  action (`"delivery_mode": "foreground"`) reports `effect: "confirmed"` when
-  the target opened or closed a window during the wait. A dialog that maps after a shorter wait
-  leaves the action `unverifiable`. Qt file dialogs can take 300 to 600 ms to
-  map. With `0`, foreground actions never report window-change evidence. Focus
-  checks and `suspected_noop` detection are unchanged.
-- **Windows: no effect.** The Windows adapter does not wait for window changes
-  after an action, so it ignores both variables.
-
-Measured on macOS with Calculator in the background and Terminal frontmost, a
-background AX click took 1153 ms with the default, 325 ms with `200`, and 78 ms
-with `0`.
-
-### Steps inside `run_steps` and `run_script` (macOS)
-
-Two waits make up most of a macOS action's latency: the agent cursor's glide to
-the target (600 ms or more with the default `steady` timing) and the first 300 ms
-of the window watch above. A call that is one step of a `run_steps` batch or a
-`run_script` program is followed at once by another step, so the driver shortens
-both for it: the step waits at most 120 ms for the cursor to arrive and 100 ms
-for a window change. The cursor keeps gliding and the watch keeps running
-detached, as above, so a window that opens late is still reported on the next
-action's result. The last step of a `run_steps` batch, and every direct call,
-keep the full waits, so the batch's final result still reports what it left
-open. A script has no last step the driver can know in advance; read the window
-with `getState()` or `waitFor()` after the action that opens something.
-
-An embedding host that wants every step to play the full glide and watch, for
-example to record a demo, sets `CUA_DRIVER_BATCH_PACING=full` in the same
-environment as the variables above. Any other value, or none, applies the
-shortened waits. No tool argument can change it.
-
-## Pacing synthesized keystrokes (macOS)
-
-The macOS keyboard adapter waits a fixed gap between each key down and up and
-between consecutive keys. For `type_text`, `press_key`, and `hotkey`, that gap
-is most of the call's latency. A host whose targets accept faster input can
-shorten it at trusted launch with one variable, in the same environment as the
-window-observation variables above. `EmbeddedCuaDriverHost` admits it too:
-
-| Variable                | Meaning                                         | Default | Accepted range                                        |
-| ----------------------- | ----------------------------------------------- | ------- | ----------------------------------------------------- |
-| `CUA_DRIVER_KEY_GAP_MS` | Gap between synthesized key events, per event.  | 8       | 2 to 100; smaller values are raised, larger clamped   |
-
-Unset, empty, or unparsable values keep the default. No tool argument can
-change the gap. An explicit `type_text` `delay_ms` still applies on top of it.
-
-- **macOS only.** Linux keeps its fixed 10 ms key delay and Windows its own
-  pacing; neither reads this variable.
-- **What a shorter gap costs.** Some targets coalesce or drop key events that
-  arrive back to back, most often remote-input forwarders and apps under heavy
-  load. Read the field back after typing before relying on a low value for a
-  new target. The 2 ms floor exists because `0` posts events with no gap at all.
-
-Measured on macOS 27 with TextEdit in the background, typing a 185-character
-ASCII sentence through the PID-routed key path took about 3650 ms at the default
-and about 980 ms at `2`. All ten read-backs (five per value) matched exactly.
-
-## What embedded mode changes (and what it doesn't)
-
-|                                               | Standalone                    | Embedded (`CUA_DRIVER_EMBEDDED=1`)     |
-| --------------------------------------------- | ----------------------------- | -------------------------------------- |
-| Responsibility disclaim re-exec               | ON (owns its TCC identity)    | OFF (stays in the host's chain)        |
-| Tool execution process                        | `serve` daemon                | host-spawned `serve --embedded` daemon |
-| Daemon auto-relaunch of the installed app     | Yes, when installed           | Never (would leave the host's chain)   |
-| TCC identity                                  | `com.trycua.driver`           | the host app                           |
-| Permission prompts / startup gate             | May prompt once               | **Never prompts**                      |
-| Settings → Privacy & Security entries         | CuaDriver                     | your app only                          |
-| `check_permissions` `source.attribution`      | `driver-daemon` (or `caller`) | `host`                                 |
-| Overlay, background input, capture, all tools | full                          | full, identical                       |
-
-Everything else is unchanged: the agent-cursor overlay, background (no-focus-steal)
-clicking and typing, AX tree reads, and per-window screenshots.
-When embedded mode is off, nothing in this feature is active: standalone
-behavior is byte-for-byte what it was.
-
-## The responsibility-chain requirement, exactly
-
-The host must be the responsible process for the driver. That holds
-automatically when you spawn the `serve` daemon directly and embedded mode
-is on. If the daemon were allowed to disclaim (standalone behavior), macOS
-would treat it as its own responsible process: your user would get a _second_ prompt
-attributed to the driver binary, a second Settings entry, and capture/AX
-would fail until that second grant. That is the exact experience embedding exists
-to eliminate. Embedded mode short-circuits the disclaim re-exec
-(`responsibility.rs`) and the installed-app daemon relaunch. MCP is
-always a proxy, so the embedded daemon remains the single process that checks
-TCC and executes tools.
-
-### App + gateway architectures
-
-`--embedded` does not transfer a GUI app's permissions to the driver; it
-only keeps the driver inside its **spawner's** TCC responsibility chain. If
-your product has a GUI app that owns the macOS grants and a separate
-gateway, daemon, or Node process that spawns MCP servers, registering
-`cua-driver serve --embedded` with the gateway makes the daemon inherit the
-gateway's identity, not the app's. Spawn the daemon from the GUI app itself;
-gateways may connect an MCP proxy to the app-owned private socket.
-
-```text
-Wrong (inherits the gateway's identity):        Right:
-
-gateway / node daemon                           YourApp.app
-  └─ cua-driver serve --embedded                  ├─ cua-driver serve --embedded
-                                                  └─ cua-driver mcp --embedded
-                                                     --socket <private-path>
-```
-
-`health_report(include=["bundle_identity"])` detects this wiring error by
-resolving the daemon's direct parent through macOS. It fails when the parent
-is not an identifiable app or when its observed bundle identifier differs
-from `CUA_DRIVER_HOST_BUNDLE_ID`. `check_permissions.source.attribution`
-still describes the configured mode; use the two reports together when
-diagnosing embedding.
-
-## Reading `check_permissions` from the host
-
-Call the `check_permissions` tool over MCP. In embedded mode it never raises
-a dialog (the `prompt` argument is ignored) and returns:
-
-```json
-{
-  "accessibility": true,
-  "screen_recording": true,
-  "screen_recording_capturable": null,
-  "direct_capture_status": "not_checked",
-  "source": {
-    "attribution": "host",
-    "host_bundle_id": "com.yourco.yourapp",
-    "embedded": true,
-    "pid": 12345,
-    "responsible_ppid": 12300,
-    "executable": "/path/to/cua-driver",
-    "disclaim_env": false,
-    "note": "Embedded mode: these booleans reflect the HOST app's TCC grant…"
-  }
-}
-```
-
-- `accessibility` / `screen_recording`: the live TCC state _of your app's
-  grant_, answered from inside the driver process (which shares your
-  identity). If both are true, it is safe to drive the desktop.
-- `screen_recording_capturable` / `direct_capture_status`: embedded
-  `check_permissions` is read-only and never runs Tahoe's prompt-capable
-  ScreenCaptureKit probe, so these are `null` / `not_checked`. The host owns
-  the permission UX and should verify pixels with an explicit screenshot or
-  capture operation after explaining the prompt.
-- `source.attribution` values:
-  - `host`: embedded mode; booleans reflect the host's grant. What you
-    should always see when embedding.
-  - `driver-daemon`: standalone daemon owning `com.trycua.driver`. If you
-    see this while embedding, embedded mode is not actually set.
-  - `caller`: a non-embedded, non-bundle launch (e.g. someone ran the
-    binary from a terminal); booleans reflect the terminal's grants.
-
-If a permission is missing, the correct reaction is: **the host requests
-it** (the two API calls above), then re-calls `check_permissions`. The
-driver never owns the host's OS permission experience.
-
-Heads-up on grant timing: macOS caches TCC answers per process. If your app
-requests/receives the grants _after_ the driver child is already running,
-restart the driver child so it re-queries with a fresh cache.
-
-## Minimal host example (copy-paste)
-
-The file below is the complete reference host: mirrored verbatim from
-`libs/cua-driver/rust/examples/embedded-host-macos/ExampleAgentHarness.swift`
-in the cua repo (which also has a build-and-run `demo.sh` covering the
-TCC-reset flow).
-It requests the two grants as the host, spawns an embedded daemon plus an MCP
-proxy, and runs the whole demo sequence: attribution check, background screenshot,
-background AX read, agent-cursor glide.
-
-`ExampleAgentHarness.swift`:
-
-```swift
-// SPDX-License-Identifier: MIT
-// Copyright (c) 2026 Cua AI, Inc.
-
-// ExampleAgentHarness: minimal reference host for embedding cua-driver.
-// Mirrored verbatim in Skills/cua-driver/EMBEDDING.md ("Minimal host
-// example"): keep the two in sync.
-//
-// Runs the one-grant demo sequence from EMBEDDING.md end to end:
-//   1. Requests Accessibility + Screen Recording AS THE HOST (the only
-//      prompts the user ever sees), then
-//   2. spawns an embedded cua-driver daemon plus its stdio MCP proxy and
-//      verifies attribution, takes a background screenshot,
-//      reads a background app's window state, and glides the agent-cursor
-//      overlay, with zero driver-side prompts.
-//
-// Launched via `open` (see demo.sh) the app has no terminal, so all
-// output also goes to /tmp/cua-embedded-demo.log.
-
-import Foundation
-import ApplicationServices
-import CoreGraphics
-
-let logPath = "/tmp/cua-embedded-demo.log"
-FileManager.default.createFile(atPath: logPath, contents: nil)
-let logFile = FileHandle(forWritingAtPath: logPath)!
-func log(_ line: String) {
-    print(line)
-    logFile.write((line + "\n").data(using: .utf8)!)
-}
-
-// 1. Request both grants AS THE HOST: the only prompts in the whole flow.
-let axOpts = ["AXTrustedCheckOptionPrompt": true] as CFDictionary
-let ax = AXIsProcessTrustedWithOptions(axOpts)
-let sr = CGRequestScreenCaptureAccess()
-log("host grants, accessibility: \(ax), screen recording: \(sr)")
-// Keep going even without grants: the run registers BOTH rows in one pass
-// (the AX request above, plus, on newer macOS, where the app only appears
-// in the Screen Recording pane after a real ScreenCaptureKit attempt, the
-// embedded driver's live probe below, registered as THE HOST, which is the
-// point of embedding). Grant both in one Settings visit, then re-run.
-if !ax || !sr {
-    log("after this run: grant the missing item(s) in System Settings, then re-run")
-}
-
-// 2. Spawn the daemon as a DIRECT child (never via `open`/NSWorkspace:
-//    that breaks responsibility inheritance), then attach an MCP proxy.
-let driverPath = ProcessInfo.processInfo.environment["CUA_DRIVER_PATH"]
-    ?? "/usr/local/bin/cua-driver"
-let socketPath = "/tmp/cua-embedded-\(ProcessInfo.processInfo.processIdentifier).sock"
-var env = ProcessInfo.processInfo.environment
-env["CUA_DRIVER_EMBEDDED"] = "1"
-env["CUA_DRIVER_HOST_BUNDLE_ID"] = Bundle.main.bundleIdentifier ?? ""
-
-let daemon = Process()
-daemon.executableURL = URL(fileURLWithPath: driverPath)
-daemon.arguments = ["serve", "--embedded", "--socket", socketPath]
-daemon.environment = env
-daemon.standardOutput = logFile
-daemon.standardError = logFile
-try daemon.run()
-
-let deadline = Date().addingTimeInterval(10)
-while !FileManager.default.fileExists(atPath: socketPath) && Date() < deadline {
-    Thread.sleep(forTimeInterval: 0.05)
-}
-guard FileManager.default.fileExists(atPath: socketPath) else {
-    log("embedded daemon did not create \(socketPath)")
-    daemon.terminate()
-    exit(1)
-}
-
-let driver = Process()
-driver.executableURL = URL(fileURLWithPath: driverPath)
-driver.arguments = ["mcp", "--embedded", "--socket", socketPath]
-driver.environment = env
-let toDriver = Pipe(), fromDriver = Pipe()
-driver.standardInput = toDriver
-driver.standardOutput = fromDriver
-try driver.run()
-
-// 3. Line-delimited JSON-RPC 2.0 over the child's stdio.
-var buffer = Data()
-func send(_ obj: [String: Any]) {
-    var data = try! JSONSerialization.data(withJSONObject: obj)
-    data.append(0x0A)
-    toDriver.fileHandleForWriting.write(data)
-}
-func readMessage() -> [String: Any] {
-    while true {
-        if let nl = buffer.firstIndex(of: 0x0A) {
-            let line = buffer.subdata(in: buffer.startIndex..<nl)
-            buffer.removeSubrange(buffer.startIndex...nl)
-            if line.isEmpty { continue }
-            return (try? JSONSerialization.jsonObject(with: line)) as? [String: Any] ?? [:]
-        }
-        let chunk = fromDriver.fileHandleForReading.availableData
-        if chunk.isEmpty { log("driver exited unexpectedly"); exit(1) }
-        buffer.append(chunk)
-    }
-}
-var nextId = 0
-func call(_ tool: String, _ args: [String: Any] = [:]) -> [String: Any] {
-    nextId += 1
-    send(["jsonrpc": "2.0", "id": nextId, "method": "tools/call",
-          "params": ["name": tool, "arguments": args]])
-    while true {
-        let msg = readMessage()
-        if msg["id"] as? Int == nextId {
-            if let error = msg["error"] as? [String: Any] {
-                log("RPC error for \(tool): \(error)")
-            }
-            return msg["result"] as? [String: Any] ?? [:]
-        }
-    }
-}
-
-nextId += 1
-send(["jsonrpc": "2.0", "id": nextId, "method": "initialize", "params": [
-    "protocolVersion": "2024-11-05", "capabilities": [:],
-    "clientInfo": ["name": "ExampleAgentHarness", "version": "0.1"]]])
-_ = readMessage()
-send(["jsonrpc": "2.0", "method": "notifications/initialized"])
-log("embedded cua-driver daemon + proxy started (\(driverPath)): no driver prompt should have appeared")
-
-// 4. health_report must observe this actual parent app, and
-//    check_permissions must report host attribution and matching TCC results.
-let health = call("health_report", ["include": ["bundle_identity"]])
-let healthStructured = health["structuredContent"] as? [String: Any] ?? [:]
-let healthChecks = healthStructured["checks"] as? [[String: Any]] ?? []
-let identity = healthChecks.first { $0["name"] as? String == "bundle_identity" } ?? [:]
-let identityData = identity["data"] as? [String: Any] ?? [:]
-let hostBundleId = Bundle.main.bundleIdentifier ?? ""
-let identityOk = identity["status"] as? String == "pass" &&
-    identityData["bundle_identifier"] as? String == hostBundleId &&
-    identityData["identity_source"] as? String == "parent_application" &&
-    (identityData["parent_process_id"] as? Int) == Int(ProcessInfo.processInfo.processIdentifier)
-log("health_report: bundle_identity: \(identity["status"] ?? "?"), " +
-    "observed host: \(identityData["bundle_identifier"] ?? "?") (want: \(hostBundleId))")
-
-let perms = call("check_permissions")
-let structured = perms["structuredContent"] as? [String: Any] ?? [:]
-let source = structured["source"] as? [String: Any] ?? [:]
-let attribution = source["attribution"] as? String ?? "?"
-let permissionsMatchHost = structured["accessibility"] as? Bool == ax &&
-    structured["screen_recording"] as? Bool == sr
-log("check_permissions: attribution: \(attribution) (want: host), " +
-    "TCC matches host: \(permissionsMatchHost), " +
-    "capturable: \(structured["screen_recording_capturable"] ?? "?")")
-
-// 5. Background AX read + window screenshot: proves both grants
-//    inherited without focusing anything. launch_app resolves pid +
-//    windows without foregrounding; get_window_state returns the AX
-//    element tree AND a screenshot of the (background) window.
-let launch = call("launch_app", ["bundle_id": "com.apple.finder"])
-let launched = launch["structuredContent"] as? [String: Any] ?? [:]
-let pid = launched["pid"] as? Int ?? 0
-let windows = launched["windows"] as? [[String: Any]] ?? []
-let windowId = windows.first?["window_id"] as? Int ?? 0
-log("launch_app(Finder): pid: \(pid), windows: \(windows.count)")
-
-let state = call("get_window_state", ["pid": pid, "window_id": windowId])
-let images = (state["content"] as? [[String: Any]] ?? [])
-    .filter { $0["type"] as? String == "image" }
-let hasTree = (state["structuredContent"] as? [String: Any])?["elements"] != nil
-log("get_window_state(Finder): tree: \(hasTree ? "ok" : "EMPTY"), " +
-    "screenshot: \(images.count) image(s) (want: ≥1)")
-
-// 6. Agent-cursor glide: shows the overlay, no real-pointer move.
-log("watch the agent cursor glide now (no real-pointer move)…")
-let cursor1 = call("move_cursor", ["x": 200, "y": 200])
-Thread.sleep(forTimeInterval: 2)
-let cursor2 = call("move_cursor", ["x": 900, "y": 500])
-Thread.sleep(forTimeInterval: 2)
-let cursorOk = (cursor1["isError"] as? Bool) != true &&
-    (cursor2["isError"] as? Bool) != true
-log("move_cursor: \(cursorOk ? "ok" : "FAILED")")
-
-let pass = identityOk && attribution == "host" && permissionsMatchHost &&
-    !images.isEmpty && hasTree && cursorOk
-log(pass ? "DEMO COMPLETE: PASS" : "DEMO COMPLETE: FAIL")
-driver.terminate()
-daemon.terminate()
-exit(pass ? 0 : 1)
-```
-
-Build it as a signed app bundle (a stable signing identity is what keys
-the TCC grant rows to your app):
-
-```sh
-mkdir -p ExampleAgentHarness.app/Contents/MacOS
-swiftc -O ExampleAgentHarness.swift \
-  -o ExampleAgentHarness.app/Contents/MacOS/ExampleAgentHarness \
-  -framework ApplicationServices
-printf '%s\n' '<?xml version="1.0" encoding="UTF-8"?>' \
-  '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">' \
-  '<plist version="1.0"><dict>' \
-  '<key>CFBundleExecutable</key><string>ExampleAgentHarness</string>' \
-  '<key>CFBundleIdentifier</key><string>com.trycua.example-agent-harness</string>' \
-  '<key>CFBundlePackageType</key><string>APPL</string>' \
-  '</dict></plist>' > ExampleAgentHarness.app/Contents/Info.plist
-codesign --force --sign - ExampleAgentHarness.app   # use your Developer ID in production
-open ExampleAgentHarness.app   # `open` is correct HERE: the HOST must be its own responsible process
-tail -f /tmp/cua-embedded-demo.log
-```
-
-## Troubleshooting
-
-**"I still get a second permission prompt / a second Settings entry."**
-Embedded mode is not in effect for the process doing the TCC check. Causes,
-in order of likelihood: (a) `CUA_DRIVER_EMBEDDED` is not exactly `1`, or was
-set on your app but not passed into the daemon child's environment; (b) the daemon
-was launched via `open(1)` / `NSWorkspace` instead of spawned directly, so
-it is its own responsible process; (c) the MCP proxy connected to an old standalone `CuaDriver.app` daemon. Check
-`check_permissions` → `source.attribution` (must be `host`) and verify
-that the proxy uses the host's private socket. To see exactly which identity macOS is charging,
-run: `log stream --debug --predicate 'subsystem == "com.apple.TCC" AND
-eventMessage BEGINSWITH "AttributionChain"'` and trigger the action again.
-
-**"Screenshots come back black even though `screen_recording: true`."**
-The read-only permission check cannot verify direct ScreenCaptureKit access
-without risking a system dialog. Exercise an explicit screenshot only after
-the host has explained the OS permission. If that fails, the grant may not
-belong to the driver's current responsible identity, may have been reset, or
-the driver may have escaped the host's chain (see the previous item). Restart
-the driver child after any grant change: TCC answers are cached per process.
-
-**"The AX tree comes back empty / clicks do nothing."**
-`AXIsProcessTrusted()` is false for the effective identity. The host hasn't
-been granted Accessibility, or was granted it _after_ the driver child
-started (per-process cache again: restart the child), or the app was
-re-signed/moved so the existing grant row no longer matches it (remove and
-re-add it in System Settings, or `tccutil reset Accessibility <your-bundle-id>`
-and re-grant).
-
-**"It worked, then stopped after I updated/re-signed my app."**
-TCC grant rows are keyed to the app's code-signing identity. A signature
-change can orphan the old row. Reset and re-grant:
-`tccutil reset Accessibility com.yourco.yourapp && tccutil reset ScreenCapture com.yourco.yourapp`.
-
-## Platform notes (Windows / Linux)
-
-Embedding also works on Windows and Linux (X11) with **no per-app permission
-ceremony**. The host still spawns a daemon in the intended interactive session
-or desktop, then points MCP and CLI adapters at its private socket. The
-one-grant inheritance story in this guide is macOS-specific because macOS is
-the platform where Accessibility and Screen Recording grants follow the
-responsibility chain.
-
-Two known exceptions:
-
-- **Windows, elevated / UWP targets**: pixel or SendInput delivery into a
-  higher-integrity target requires an interactively launched High-IL daemon
-  (the installed autostart task uses `RunLevel=Highest`). The
-  `cua-driver-uia` pipe is a reserved, default-off daemon-internal boundary;
-  embedding hosts and other public clients must not launch or connect to it.
-- **Linux Wayland** (compositor-specific): capture goes through XDG desktop
-  portals, which prompt per-session at capture time and cannot be
-  pre-granted by the host. X11 has no portal gate.