@trycua/cua-driver 0.35.2 → 0.36.0

package/dist/daemon.d.ts

@@ -0,0 +1,14 @@
+export interface Availability {
+    isAvailable(): boolean;
+}
+export interface CreateDriverHooks {
+    platform?: NodeJS.Platform;
+    appInstalled?: () => boolean;
+    launch?: () => boolean;
+    timeoutMs?: number;
+    sleep?: (ms: number) => void;
+    warn?: (message: string) => void;
+}
+/** Reset the one-time warning (tests only). */
+export declare function resetDaemonWarning(): void;
+export declare function createDriver<T extends Availability>(connect: () => T, createEmbedded: () => T, embedded: boolean, claudeCodeCompatibility: boolean, hooks?: CreateDriverHooks): T;

package/dist/daemon.js

@@ -0,0 +1,59 @@
+/**
+ * macOS daemon preference for `CuaDriver.create()`.
+ *
+ * An embedded (in-process) runtime on macOS has no AppKit host, so the agent
+ * cursor overlay cannot be drawn and permissions are attributed to the host
+ * process. The daemon (CuaDriver.app running `serve`) draws the cursor and owns
+ * the TCC grants, so on macOS `create()` connects to it, starting it through
+ * LaunchServices when the app is installed. No native dependency, so it is
+ * testable without the staged library.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+const APP_NAME = "CuaDriver";
+const APP_PATH = `/Applications/${APP_NAME}.app`;
+const EMBEDDED_ENV = "CUA_DRIVER_EMBEDDED";
+let warned = false;
+/** Reset the one-time warning (tests only). */
+export function resetDaemonWarning() {
+    warned = false;
+}
+function launchApp() {
+    const result = spawnSync("/usr/bin/open", ["-n", "-g", "-a", APP_NAME, "--args", "serve"], { stdio: "ignore" });
+    return result.status === 0;
+}
+function blockingSleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+export function createDriver(connect, createEmbedded, embedded, claudeCodeCompatibility, hooks = {}) {
+    const platform = hooks.platform ?? process.platform;
+    if (embedded ||
+        claudeCodeCompatibility ||
+        platform !== "darwin" ||
+        process.env[EMBEDDED_ENV] === "1") {
+        return createEmbedded();
+    }
+    const driver = connect();
+    if (driver.isAvailable())
+        return driver;
+    const installed = (hooks.appInstalled ?? (() => existsSync(APP_PATH)))();
+    if (installed && (hooks.launch ?? launchApp)()) {
+        const sleep = hooks.sleep ?? blockingSleep;
+        const deadline = Date.now() + (hooks.timeoutMs ?? 15_000);
+        while (Date.now() < deadline) {
+            if (driver.isAvailable())
+                return driver;
+            sleep(250);
+        }
+    }
+    if (!warned) {
+        warned = true;
+        const message = "CuaDriver.create() is using the in-process runtime, which cannot draw " +
+            "the agent cursor on macOS and attributes permissions to this process. " +
+            "Install CuaDriver.app and run `cua-driver serve` (or call " +
+            "CuaDriver.connect()) to get the agent cursor, or pass " +
+            "{ embedded: true } to silence this warning.";
+        (hooks.warn ?? ((m) => process.emitWarning(m)))(message);
+    }
+    return createEmbedded();
+}

package/dist/index.d.ts

@@ -1,2 +1,22 @@
+/**
+ * Rust-backed SDK for Cua Driver client applications.
+ *
+ * Agents should configure `cua-driver mcp` through their runtime's existing
+ * MCP client instead of importing a language MCP facade.
+ */
+import { CuaDriver as NativeCuaDriver, type CuaDriverLike, type DriverOptions } from "./native/cua_driver_sdk.js";
+/**
+ * Options for `CuaDriver.create()`. `embedded: true` forces the in-process
+ * runtime on macOS, where `create()` otherwise prefers the CuaDriver.app
+ * daemon so the agent cursor overlay and the app's permissions work.
+ */
+export type CreateOptions = DriverOptions & {
+    embedded?: boolean;
+};
+declare const CuaDriver: typeof NativeCuaDriver & {
+    create(options?: CreateOptions): CuaDriverLike;
+};
+type CuaDriver = NativeCuaDriver;
 export * from "./native/index.js";
+export { CuaDriver };
 export { default } from "./native/index.js";

package/dist/index.js

@@ -4,16 +4,22 @@
  * Agents should configure `cua-driver mcp` through their runtime's existing
  * MCP client instead of importing a language MCP facade.
  */
-import { CuaDriver, SdkClientKind } from "./native/cua_driver_sdk.js";
+import { CuaDriver as NativeCuaDriver, SdkClientKind, } from "./native/cua_driver_sdk.js";
+import { createDriver } from "./daemon.js";
+const CuaDriver = NativeCuaDriver;
 // The same native library backs Python and TypeScript. The package root tags
 // both the canonical same-process constructor and the temporary daemon
 // compatibility constructor with the importing runtime.
-CuaDriver.create = (options) => CuaDriver.createWithClientKind(options, SdkClientKind.Typescript);
-CuaDriver.createConfigured = (options) => CuaDriver.createConfiguredWithClientKind(options, SdkClientKind.Typescript);
-CuaDriver.createConfiguredWithAuthorizationHost = (options, host) => CuaDriver.createConfiguredWithAuthorizationHostAndClientKind(options, host, SdkClientKind.Typescript);
-CuaDriver.createConfiguredWithActivityObserver = (options, observer) => CuaDriver.createConfiguredWithActivityObserverAndClientKind(options, observer, SdkClientKind.Typescript);
-CuaDriver.createConfiguredWithHostIntegrations = (options, host, observer) => CuaDriver.createConfiguredWithHostIntegrationsAndClientKind(options, host, observer, SdkClientKind.Typescript);
-CuaDriver.createPrivateWorker = (options) => CuaDriver.createPrivateWorkerWithClientKind(options, SdkClientKind.Typescript);
-CuaDriver.connect = (socketPath) => CuaDriver.connectWithClientKind(socketPath, SdkClientKind.Typescript);
+NativeCuaDriver.create = (options) => {
+    const { embedded, ...driverOptions } = options ?? {};
+    return createDriver(() => NativeCuaDriver.connectWithClientKind(undefined, SdkClientKind.Typescript), () => NativeCuaDriver.createWithClientKind(options === undefined ? undefined : driverOptions, SdkClientKind.Typescript), embedded === true, driverOptions.claudeCodeCompatibility === true);
+};
+NativeCuaDriver.createConfigured = (options) => NativeCuaDriver.createConfiguredWithClientKind(options, SdkClientKind.Typescript);
+NativeCuaDriver.createConfiguredWithAuthorizationHost = (options, host) => NativeCuaDriver.createConfiguredWithAuthorizationHostAndClientKind(options, host, SdkClientKind.Typescript);
+NativeCuaDriver.createConfiguredWithActivityObserver = (options, observer) => NativeCuaDriver.createConfiguredWithActivityObserverAndClientKind(options, observer, SdkClientKind.Typescript);
+NativeCuaDriver.createConfiguredWithHostIntegrations = (options, host, observer) => NativeCuaDriver.createConfiguredWithHostIntegrationsAndClientKind(options, host, observer, SdkClientKind.Typescript);
+NativeCuaDriver.createPrivateWorker = (options) => NativeCuaDriver.createPrivateWorkerWithClientKind(options, SdkClientKind.Typescript);
+NativeCuaDriver.connect = (socketPath) => NativeCuaDriver.connectWithClientKind(socketPath, SdkClientKind.Typescript);
 export * from "./native/index.js";
+export { CuaDriver };
 export { default } from "./native/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trycua/cua-driver",
-  "version": "0.35.2",
+  "version": "0.36.0",
   "description": "Rust-backed Cua Driver SDK and embedded Node host",
   "type": "module",
   "license": "MIT",
@@ -38,7 +38,9 @@
     "dist/fleet.js",
     "dist/fleet.d.ts",
     "dist/native",
-    "README.md"
+    "README.md",
+    "dist/daemon.js",
+    "dist/daemon.d.ts"
   ],
   "publishConfig": {
     "access": "public"
@@ -48,11 +50,11 @@
     "@ubjs/node": "0.31.0-3"
   },
   "optionalDependencies": {
-    "@trycua/cua-driver-darwin-arm64": "0.35.2",
-    "@trycua/cua-driver-darwin-x64": "0.35.2",
-    "@trycua/cua-driver-linux-arm64-gnu": "0.35.2",
-    "@trycua/cua-driver-linux-x64-gnu": "0.35.2",
-    "@trycua/cua-driver-win32-arm64-msvc": "0.35.2",
-    "@trycua/cua-driver-win32-x64-msvc": "0.35.2"
+    "@trycua/cua-driver-darwin-arm64": "0.36.0",
+    "@trycua/cua-driver-darwin-x64": "0.36.0",
+    "@trycua/cua-driver-linux-arm64-gnu": "0.36.0",
+    "@trycua/cua-driver-linux-x64-gnu": "0.36.0",
+    "@trycua/cua-driver-win32-arm64-msvc": "0.36.0",
+    "@trycua/cua-driver-win32-x64-msvc": "0.36.0"
   }
 }