Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

fix(cua-driver): support Electron UniFFI buffers (#2455)

Francesco Bonaccid3bf82a2cbb2
diff --git a/.github/workflows/cd-py-cua-driver.yml b/.github/workflows/cd-py-cua-driver.yml
index dfb57ada6b..018c9f9d2d 100644
--- a/.github/workflows/cd-py-cua-driver.yml
+++ b/.github/workflows/cd-py-cua-driver.yml
@@ -233,17 +233,24 @@ jobs:
"$RUNNER_TEMP/cua-driver-native/win32-arm64-msvc"
tar -xzf "$RUNNER_TEMP"/cua-driver-assets/*-darwin-universal-binary.tar.gz \
- -C "$RUNNER_TEMP/cua-driver-native/darwin-arm64" libcua_driver_sdk.dylib
+ -C "$RUNNER_TEMP/cua-driver-native/darwin-arm64" \
+ libcua_driver_sdk.dylib cua_driver_node_runtime.node
cp "$RUNNER_TEMP/cua-driver-native/darwin-arm64/libcua_driver_sdk.dylib" \
"$RUNNER_TEMP/cua-driver-native/darwin-x64/libcua_driver_sdk.dylib"
+ cp "$RUNNER_TEMP/cua-driver-native/darwin-arm64/cua_driver_node_runtime.node" \
+ "$RUNNER_TEMP/cua-driver-native/darwin-x64/cua_driver_node_runtime.node"
tar -xzf "$RUNNER_TEMP"/cua-driver-assets/*-linux-x86_64-binary.tar.gz \
- -C "$RUNNER_TEMP/cua-driver-native/linux-x64-gnu" libcua_driver_sdk.so
+ -C "$RUNNER_TEMP/cua-driver-native/linux-x64-gnu" \
+ libcua_driver_sdk.so cua_driver_node_runtime.node
tar -xzf "$RUNNER_TEMP"/cua-driver-assets/*-linux-arm64-binary.tar.gz \
- -C "$RUNNER_TEMP/cua-driver-native/linux-arm64-gnu" libcua_driver_sdk.so
+ -C "$RUNNER_TEMP/cua-driver-native/linux-arm64-gnu" \
+ libcua_driver_sdk.so cua_driver_node_runtime.node
unzip -j "$RUNNER_TEMP"/cua-driver-assets/*-windows-x86_64-binary.zip \
- cua_driver_sdk.dll -d "$RUNNER_TEMP/cua-driver-native/win32-x64-msvc"
+ cua_driver_sdk.dll cua_driver_node_runtime.node \
+ -d "$RUNNER_TEMP/cua-driver-native/win32-x64-msvc"
unzip -j "$RUNNER_TEMP"/cua-driver-assets/*-windows-arm64-binary.zip \
- cua_driver_sdk.dll -d "$RUNNER_TEMP/cua-driver-native/win32-arm64-msvc"
+ cua_driver_sdk.dll cua_driver_node_runtime.node \
+ -d "$RUNNER_TEMP/cua-driver-native/win32-arm64-msvc"
- name: Pack root and platform npm packages
run: |
node libs/cua-driver/scripts/build-npm-packages.mjs \
diff --git a/.github/workflows/cd-rust-cua-driver.yml b/.github/workflows/cd-rust-cua-driver.yml
index 7f16ce518c..688d9371e4 100644
--- a/.github/workflows/cd-rust-cua-driver.yml
+++ b/.github/workflows/cd-rust-cua-driver.yml
@@ -96,6 +96,11 @@ jobs:
- uses: actions/checkout@v4
with:
ref: ${{ github.event_name == 'workflow_dispatch' && inputs.publish && format('refs/tags/cua-driver-rs-v{0}', inputs.version) || github.ref }}
+ - uses: actions/setup-node@v4
+ with:
+ node-version: "22"
+ cache: npm
+ cache-dependency-path: libs/cua-driver/typescript/package-lock.json
- name: Determine version
id: version
shell: bash
@@ -121,6 +126,13 @@ jobs:
- name: Build (release)
working-directory: libs/cua-driver/rust
run: cargo build --locked -p cua-driver -p cua-driver-sdk --release --features cua-driver/portal-input --target ${{ matrix.target }}
+ - name: Build Electron-compatible Node runtime
+ working-directory: libs/cua-driver
+ run: |
+ npm --prefix typescript ci --ignore-scripts
+ node scripts/build-node-runtime.mjs \
+ --target "${{ matrix.target }}" \
+ --output "rust/target/${{ matrix.target }}/release/cua_driver_node_runtime.node"
- name: Package
working-directory: libs/cua-driver/rust
run: |
@@ -131,12 +143,13 @@ jobs:
mkdir -p "release/${STAGE}"
cp "target/${TARGET}/release/cua-driver" "release/${STAGE}/"
cp "target/${TARGET}/release/libcua_driver_sdk.so" "release/${STAGE}/"
+ cp "target/${TARGET}/release/cua_driver_node_runtime.node" "release/${STAGE}/"
cp ../../LICENSE.md "release/${STAGE}/LICENSE" 2>/dev/null || true
(cd release && tar -czf "${STAGE}.tar.gz" "${STAGE}")
# Bare runtime tarball: CLI plus the UniFFI library consumed by the
# Python and Node imported-SDK packages.
tar -czf "release/${STAGE}-binary.tar.gz" -C "release/${STAGE}" \
- cua-driver libcua_driver_sdk.so
+ cua-driver libcua_driver_sdk.so cua_driver_node_runtime.node
ls -lh "release/${STAGE}.tar.gz" "release/${STAGE}-binary.tar.gz"
- uses: actions/upload-artifact@v4
with:
@@ -164,6 +177,11 @@ jobs:
- uses: actions/checkout@v4
with:
ref: ${{ github.event_name == 'workflow_dispatch' && inputs.publish && format('refs/tags/cua-driver-rs-v{0}', inputs.version) || github.ref }}
+ - uses: actions/setup-node@v4
+ with:
+ node-version: "22"
+ cache: npm
+ cache-dependency-path: libs/cua-driver/typescript/package-lock.json
- name: Determine version
id: version
shell: bash
@@ -203,6 +221,14 @@ jobs:
# at UIAccess integrity so SendInput / UI Automation can cross UIPI
# into UWP apps — see crates/cua-driver-uia/ and #1602.
run: cargo build --locked -p cua-driver -p cua-driver-uia -p cua-driver-sdk --release --target ${{ matrix.target }}
+ - name: Build Electron-compatible Node runtime
+ working-directory: libs/cua-driver
+ shell: bash
+ run: |
+ npm --prefix typescript ci --ignore-scripts
+ node scripts/build-node-runtime.mjs \
+ --target "${{ matrix.target }}" \
+ --output "rust/target/${{ matrix.target }}/release/cua_driver_node_runtime.node"
- name: Package
working-directory: libs/cua-driver/rust
shell: pwsh
@@ -215,6 +241,7 @@ jobs:
Copy-Item "target/$target/release/cua-driver.exe" "release/$stage/"
Copy-Item "target/$target/release/cua-driver-uia.exe" "release/$stage/"
Copy-Item "target/$target/release/cua_driver_sdk.dll" "release/$stage/"
+ Copy-Item "target/$target/release/cua_driver_node_runtime.node" "release/$stage/"
if (Test-Path "../../LICENSE.md") { Copy-Item "../../LICENSE.md" "release/$stage/LICENSE" }
# Zip the directory itself (no trailing /*) so the archive contains
# the top-level "$stage" wrapper dir — install.ps1 walks into
@@ -229,7 +256,7 @@ jobs:
# to UIAccess integrity on a default-policy machine. The main CLI/MCP
# binary stays fully functional regardless; uia is opt-in dead-weight
# until signed.
- Compress-Archive -Path "release/$stage/cua-driver.exe","release/$stage/cua-driver-uia.exe","release/$stage/cua_driver_sdk.dll" -DestinationPath "release/$stage-binary.zip" -Force
+ Compress-Archive -Path "release/$stage/cua-driver.exe","release/$stage/cua-driver-uia.exe","release/$stage/cua_driver_sdk.dll","release/$stage/cua_driver_node_runtime.node" -DestinationPath "release/$stage-binary.zip" -Force
Get-ChildItem "release/$stage*.zip"
- uses: actions/upload-artifact@v4
with:
@@ -263,6 +290,11 @@ jobs:
- uses: actions/checkout@v4
with:
ref: ${{ github.event_name == 'workflow_dispatch' && inputs.publish && format('refs/tags/cua-driver-rs-v{0}', inputs.version) || github.ref }}
+ - uses: actions/setup-node@v4
+ with:
+ node-version: "22"
+ cache: npm
+ cache-dependency-path: libs/cua-driver/typescript/package-lock.json
- name: Determine version
id: version
shell: bash
@@ -325,6 +357,16 @@ jobs:
- name: Build x86_64
working-directory: libs/cua-driver/rust
run: cargo build --locked -p cua-driver -p cua-driver-sdk --release --target x86_64-apple-darwin
+ - name: Build Electron-compatible Node runtimes
+ working-directory: libs/cua-driver
+ run: |
+ npm --prefix typescript ci --ignore-scripts
+ node scripts/build-node-runtime.mjs \
+ --target aarch64-apple-darwin \
+ --output rust/target/aarch64-apple-darwin/release/cua_driver_node_runtime.node
+ node scripts/build-node-runtime.mjs \
+ --target x86_64-apple-darwin \
+ --output rust/target/x86_64-apple-darwin/release/cua_driver_node_runtime.node
- name: Create universal binary (lipo)
working-directory: libs/cua-driver/rust
run: |
@@ -332,11 +374,15 @@ jobs:
X86="target/x86_64-apple-darwin/release/cua-driver"
SDK_ARM64="target/aarch64-apple-darwin/release/libcua_driver_sdk.dylib"
SDK_X86="target/x86_64-apple-darwin/release/libcua_driver_sdk.dylib"
+ NODE_ARM64="target/aarch64-apple-darwin/release/cua_driver_node_runtime.node"
+ NODE_X86="target/x86_64-apple-darwin/release/cua_driver_node_runtime.node"
mkdir -p release/universal
lipo -create "$ARM64" "$X86" -output release/universal/cua-driver
lipo -create "$SDK_ARM64" "$SDK_X86" -output release/universal/libcua_driver_sdk.dylib
+ lipo -create "$NODE_ARM64" "$NODE_X86" -output release/universal/cua_driver_node_runtime.node
lipo -info release/universal/cua-driver
lipo -info release/universal/libcua_driver_sdk.dylib
+ lipo -info release/universal/cua_driver_node_runtime.node
test "$(otool -D release/universal/libcua_driver_sdk.dylib | tail -n 1)" = \
'@rpath/libcua_driver_sdk.dylib'
- name: Codesign universal binary (hardened runtime)
@@ -439,6 +485,7 @@ jobs:
# (matches the Swift `cd-swift-cua-driver.yml` convention).
cp release/universal/cua-driver "release/${STAGE}/"
cp release/universal/libcua_driver_sdk.dylib "release/${STAGE}/"
+ cp release/universal/cua_driver_node_runtime.node "release/${STAGE}/"
# Ship the .app bundle in every macOS tarball so install.sh
# can drop it into /Applications/CuaDriver.app for TCC
# attribution (issue #1525). Tarball callers that want only
@@ -450,7 +497,7 @@ jobs:
# Bare runtime tarball: universal CLI plus universal UniFFI library.
# No app bundle: callers of this asset deliberately skip that flow.
tar -czf "release/cua-driver-rs-${VERSION}-darwin-universal-binary.tar.gz" \
- -C release/universal cua-driver libcua_driver_sdk.dylib
+ -C release/universal cua-driver libcua_driver_sdk.dylib cua_driver_node_runtime.node
ls -lh release/*.tar.gz
- uses: actions/upload-artifact@v4
with:
diff --git a/.github/workflows/ci-cua-driver-contract-clients.yml b/.github/workflows/ci-cua-driver-contract-clients.yml
index b7612d47fc..cf619d9749 100644
--- a/.github/workflows/ci-cua-driver-contract-clients.yml
+++ b/.github/workflows/ci-cua-driver-contract-clients.yml
@@ -171,6 +171,8 @@ jobs:
mkdir -p /tmp/cua-driver-native/linux-x64-gnu /tmp/cua-driver-npm/smoke
cp ../rust/target/release/libcua_driver_sdk.so \
/tmp/cua-driver-native/linux-x64-gnu/libcua_driver_sdk.so
+ cp node_modules/@trycua/cua-driver-linux-x64-gnu/cua_driver_node_runtime.node \
+ /tmp/cua-driver-native/linux-x64-gnu/cua_driver_node_runtime.node
VERSION=$(node -p "require('./package.json').version")
node ../scripts/build-npm-packages.mjs \
--version "$VERSION" \
@@ -182,6 +184,8 @@ jobs:
grep -F 'package/dist/electron.js' /tmp/cua-driver-npm/contents.txt
tar -tzf "/tmp/cua-driver-npm/trycua-cua-driver-linux-x64-gnu-$VERSION.tgz" | \
grep -F 'package/libcua_driver_sdk.so'
+ tar -tzf "/tmp/cua-driver-npm/trycua-cua-driver-linux-x64-gnu-$VERSION.tgz" | \
+ grep -F 'package/cua_driver_node_runtime.node'
npm install --prefix /tmp/cua-driver-npm/smoke \
"/tmp/cua-driver-npm/trycua-cua-driver-$VERSION.tgz" \
"/tmp/cua-driver-npm/trycua-cua-driver-linux-x64-gnu-$VERSION.tgz"
diff --git a/libs/cua-driver/scripts/build-node-runtime.mjs b/libs/cua-driver/scripts/build-node-runtime.mjs
new file mode 100644
index 0000000000..9cc63908c7
--- /dev/null
+++ b/libs/cua-driver/scripts/build-node-runtime.mjs
@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+
+/**
+ * Build the pinned UBRN N-API runtime with a copy-based RustBuffer boundary.
+ *
+ * Electron 20+ rejects external ArrayBuffers. UBRN 0.31.0-3 uses them as a
+ * zero-copy optimization for every RustBuffer argument and return. The
+ * generated SDK already copies RustBuffer contents while lowering/lifting, so
+ * this compatibility build keeps the same values and ownership while using
+ * JavaScript-owned Uint8Arrays at the N-API boundary.
+ *
+ * The patched source remains MPL-2.0 and comes from the exact, pinned
+ * uniffi-bindgen-react-native development dependency.
+ */
+import { spawnSync } from "node:child_process"
+import {
+ copyFileSync,
+ cpSync,
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from "node:fs"
+import { tmpdir } from "node:os"
+import { basename, dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const scriptDirectory = dirname(fileURLToPath(import.meta.url))
+const driverRoot = resolve(scriptDirectory, "..")
+const typescriptRoot = join(driverRoot, "typescript")
+const upstreamRoot = join(
+ typescriptRoot,
+ "node_modules",
+ "uniffi-bindgen-react-native",
+)
+const outputIndex = process.argv.indexOf("--output")
+if (outputIndex < 0 || !process.argv[outputIndex + 1]) {
+ throw new Error("usage: build-node-runtime.mjs --output <path> [--target <triple>]")
+}
+const output = resolve(process.argv[outputIndex + 1])
+const targetIndex = process.argv.indexOf("--target")
+const target = targetIndex < 0 ? undefined : process.argv[targetIndex + 1]
+if (targetIndex >= 0 && !target) throw new Error("missing --target value")
+
+const manifest = JSON.parse(readFileSync(join(typescriptRoot, "package.json"), "utf8"))
+const expectedVersion = manifest.devDependencies?.["uniffi-bindgen-react-native"]
+const upstreamManifestPath = join(upstreamRoot, "package.json")
+if (!existsSync(upstreamManifestPath)) {
+ throw new Error("missing pinned UBRN source; run npm ci in libs/cua-driver/typescript")
+}
+const actualVersion = JSON.parse(readFileSync(upstreamManifestPath, "utf8")).version
+if (actualVersion !== expectedVersion) {
+ throw new Error(`UBRN source mismatch: expected ${expectedVersion}, found ${actualVersion}`)
+}
+
+function replaceOnce(source, needle, replacement, description) {
+ const matches = source.split(needle).length - 1
+ if (matches !== 1) throw new Error(`expected one ${description}, found ${matches}`)
+ return source.replace(needle, replacement)
+}
+
+function patchRegister(source) {
+ const allocStart = source.indexOf(
+ " let alloc_module = Arc::clone(&module);\n let alloc_fn =",
+ )
+ const allocEndNeedle = ' result.set_named_property("rustbuffer_alloc", alloc_fn)?;'
+ const allocEnd = source.indexOf(allocEndNeedle, allocStart)
+ if (allocStart < 0 || allocEnd < 0) throw new Error("UBRN alloc block changed")
+ source = `${source.slice(0, allocStart)} let alloc_fn = env.create_function_from_closure("rustbuffer_alloc", move |ctx| {
+ let size_arg: i32 = ctx.get(0)?;
+ if size_arg < 0 {
+ return Err(napi::Error::from_reason(
+ "rustbuffer_alloc size must be non-negative".to_string(),
+ ));
+ }
+ let len = usize::try_from(size_arg).map_err(|_| {
+ napi::Error::from_reason("RustBuffer size exceeds addressable memory".to_string())
+ })?;
+ let typedarray = unsafe {
+ napi_utils::create_uint8array(ctx.env.raw(), std::ptr::null(), len)?
+ };
+ unsafe { JsUnknown::from_raw(ctx.env.raw(), typedarray) }
+ })?;
+${source.slice(allocEnd)}`
+
+ const freeStart = source.indexOf(" let free_module = Arc::clone(&module);")
+ const freeEndNeedle = ' result.set_named_property("rustbuffer_free", free_fn)?;'
+ const freeEnd = source.indexOf(freeEndNeedle, freeStart)
+ if (freeStart < 0 || freeEnd < 0) throw new Error("UBRN free block changed")
+ return `${source.slice(0, freeStart)} let free_fn = env.create_function_from_closure("rustbuffer_free", move |ctx| {
+ // Copy-mode buffers are JavaScript-owned. RustBuffer arguments are
+ // separately allocated by rustbuffer_from_bytes inside call dispatch.
+ ctx.env.get_undefined().map(|u| u.into_unknown())
+ })?;
+${source.slice(freeEnd)}`
+}
+
+function patchCall(source) {
+ source = replaceOnce(
+ source,
+ "rust_buffer_to_js_uint8array_handoff(env, *rb, capacity_symbol)",
+ "rust_buffer_to_js_uint8array_copy(env, *rb, module.rb_ops().free_ptr)",
+ "RustBuffer return dispatch",
+ )
+ source = replaceOnce(
+ source,
+ "fn rust_buffer_to_js_uint8array_handoff(\n env: &napi::Env,\n rb: RustBufferC,\n capacity_symbol: &CapacitySymbol,\n)",
+ "fn rust_buffer_to_js_uint8array_copy(\n env: &napi::Env,\n rb: RustBufferC,\n free_ptr: *const c_void,\n)",
+ "RustBuffer return function",
+ )
+ const bodyStart = source.indexOf(
+ " // Empty RustBuffer (capacity == 0 or null data): no allocation to alias,",
+ )
+ const bodyEndNeedle = " Ok(unsafe { JsUnknown::from_raw(raw_env, typedarray)? })\n}"
+ const bodyEnd = source.indexOf(bodyEndNeedle, bodyStart)
+ if (bodyStart < 0 || bodyEnd < 0) throw new Error("UBRN RustBuffer return body changed")
+ const replacement = ` // Electron disallows external ArrayBuffers. Copy into a V8-owned
+ // Uint8Array, then release the Rust allocation before returning to JS.
+ let typedarray = unsafe { napi_utils::create_uint8array(raw_env, rb.data, len) };
+ unsafe { napi_utils::free_rustbuffer(rb, free_ptr) };
+ let typedarray = typedarray?;
+ Ok(unsafe { JsUnknown::from_raw(raw_env, typedarray)? })
+}`
+ return `${source.slice(0, bodyStart)}${replacement}${source.slice(bodyEnd + bodyEndNeedle.length)}`
+}
+
+const temporaryRoot = mkdtempSync(join(tmpdir(), "cua-driver-node-runtime-"))
+try {
+ const runtimeRoot = join(temporaryRoot, "runtime")
+ cpSync(join(upstreamRoot, "runtimes", "core"), join(runtimeRoot, "core"), {
+ recursive: true,
+ })
+ cpSync(join(upstreamRoot, "runtimes", "napi"), join(runtimeRoot, "napi"), {
+ recursive: true,
+ })
+ const registerPath = join(runtimeRoot, "napi", "src", "register", "mod.rs")
+ writeFileSync(registerPath, patchRegister(readFileSync(registerPath, "utf8")))
+ const callPath = join(runtimeRoot, "napi", "src", "call", "mod.rs")
+ writeFileSync(callPath, patchCall(readFileSync(callPath, "utf8")))
+
+ const args = ["build", "--release", "--manifest-path", join(runtimeRoot, "napi", "Cargo.toml")]
+ if (target) args.push("--target", target)
+ const result = spawnSync("cargo", args, { stdio: "inherit" })
+ if (result.error) throw result.error
+ if (result.status !== 0) throw new Error(`cargo exited with status ${result.status}`)
+
+ const targetDirectory = target
+ ? join(runtimeRoot, "napi", "target", target, "release")
+ : join(runtimeRoot, "napi", "target", "release")
+ const candidates = [
+ "libuniffi_runtime_napi.dylib",
+ "libuniffi_runtime_napi.so",
+ "uniffi_runtime_napi.dll",
+ ]
+ const built = candidates.map((name) => join(targetDirectory, name)).find(existsSync)
+ if (!built) throw new Error(`missing built N-API runtime under ${targetDirectory}`)
+ mkdirSync(dirname(output), { recursive: true })
+ copyFileSync(built, output)
+ console.log(`built ${basename(output)} from UBRN ${actualVersion}`)
+} finally {
+ rmSync(temporaryRoot, { recursive: true, force: true })
+}
diff --git a/libs/cua-driver/scripts/build-npm-packages.mjs b/libs/cua-driver/scripts/build-npm-packages.mjs
index 16da115e77..d46640c48e 100644
--- a/libs/cua-driver/scripts/build-npm-packages.mjs
+++ b/libs/cua-driver/scripts/build-npm-packages.mjs
@@ -47,6 +47,8 @@ const platforms = [
{ triple: "win32-arm64-msvc", os: "win32", cpu: "arm64", file: "cua_driver_sdk.dll" },
{ triple: "win32-x64-msvc", os: "win32", cpu: "x64", file: "cua_driver_sdk.dll" },
]
+const runtimeFile = "cua_driver_node_runtime.node"
+const runtimeNotice = "node-runtime-NOTICE.md"
function writeJson(path, value) {
writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`)
@@ -76,19 +78,25 @@ for (const platform of platforms) {
if (allowPartial) continue
throw new Error(`missing native SDK library ${source}`)
}
+ const runtimeSource = join(nativeRoot, platform.triple, runtimeFile)
+ if (!existsSync(runtimeSource)) {
+ throw new Error(`missing Electron-compatible Node runtime ${runtimeSource}`)
+ }
nativeCount += 1
const destination = join(stagingRoot, platform.triple)
mkdirSync(destination, { recursive: true })
cpSync(source, join(destination, platform.file))
+ cpSync(runtimeSource, join(destination, runtimeFile))
+ cpSync(join(scriptDirectory, runtimeNotice), join(destination, runtimeNotice))
const manifest = {
name,
version,
description: `Native Cua Driver SDK library for ${platform.triple}`,
- license: "MIT",
+ license: "MIT AND MPL-2.0",
repository: { type: "git", url: "git+https://github.com/trycua/cua.git" },
os: [platform.os],
cpu: [platform.cpu],
- files: [platform.file],
+ files: [platform.file, runtimeFile, runtimeNotice],
publishConfig: { access: "public" },
}
if (platform.libc) manifest.libc = [platform.libc]
diff --git a/libs/cua-driver/scripts/generate-uniffi-bindings.mjs b/libs/cua-driver/scripts/generate-uniffi-bindings.mjs
index e87c6922b7..6be285cd6b 100644
--- a/libs/cua-driver/scripts/generate-uniffi-bindings.mjs
+++ b/libs/cua-driver/scripts/generate-uniffi-bindings.mjs
@@ -58,6 +58,14 @@ function normalizeTypeScript(name, source) {
/(from\s+["']\.\/[A-Za-z0-9_-]+)(["'])/g,
"$1.js$2",
)
+ if (name.endsWith("-ffi.ts")) {
+ const needle = 'import lib from "@ubjs/node";'
+ const matches = output.split(needle).length - 1
+ if (matches !== 1) {
+ throw new Error(`expected one Node runtime import in ${name}, found ${matches}`)
+ }
+ output = output.replace(needle, 'import lib from "./node-runtime.js";')
+ }
if (name === "cua_driver_contract-ffi.ts") {
const needle = 'crateName: "cua_driver_contract"'
const matches = output.split(needle).length - 1
diff --git a/libs/cua-driver/scripts/node-runtime-NOTICE.md b/libs/cua-driver/scripts/node-runtime-NOTICE.md
new file mode 100644
index 0000000000..f84f0e9772
--- /dev/null
+++ b/libs/cua-driver/scripts/node-runtime-NOTICE.md
@@ -0,0 +1,12 @@
+# Cua Driver Node runtime notice
+
+`cua_driver_node_runtime.node` is a compatibility build derived from the N-API
+runtime in `uniffi-bindgen-react-native` 0.31.0-3, copyright its contributors
+and licensed under the Mozilla Public License 2.0.
+
+The corresponding source is the pinned npm development dependency plus the
+deterministic transformations in `scripts/build-node-runtime.mjs`. The source
+and build script are available in the Cua repository at the release tag that
+matches this package.
+
+<https://www.mozilla.org/MPL/2.0/>
diff --git a/libs/cua-driver/scripts/stage-uniffi-library.mjs b/libs/cua-driver/scripts/stage-uniffi-library.mjs
index 1b5e91ebe3..2c948b7b3e 100644
--- a/libs/cua-driver/scripts/stage-uniffi-library.mjs
+++ b/libs/cua-driver/scripts/stage-uniffi-library.mjs
@@ -1,5 +1,7 @@
#!/usr/bin/env node
+import { spawnSync } from "node:child_process"
+
import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs"
import { dirname, join, resolve } from "node:path"
import { fileURLToPath } from "node:url"
@@ -45,6 +47,16 @@ const localPackage = join(
)
mkdirSync(localPackage, { recursive: true })
copyFileSync(source, join(localPackage, file))
+const runtime = join(localPackage, "cua_driver_node_runtime.node")
+const runtimeBuild = spawnSync(
+ process.execPath,
+ [join(driverRoot, "scripts", "build-node-runtime.mjs"), "--output", runtime],
+ { stdio: "inherit" },
+)
+if (runtimeBuild.error) throw runtimeBuild.error
+if (runtimeBuild.status !== 0) {
+ throw new Error(`Node runtime build exited with status ${runtimeBuild.status}`)
+}
writeFileSync(
join(localPackage, "package.json"),
`${JSON.stringify(
diff --git a/libs/cua-driver/typescript/README.md b/libs/cua-driver/typescript/README.md
index 57204024a0..c0a6fc9e96 100644
--- a/libs/cua-driver/typescript/README.md
+++ b/libs/cua-driver/typescript/README.md
@@ -129,3 +129,12 @@ The npm package installs one optional native package selected for the current
OS and CPU. It does not bundle the `cua-driver` executable: ship that executable
outside ASAR, preserve its executable bit, and sign it before signing and
notarizing the enclosing app.
+
+Each native package also carries Cua's copy-mode build of the pinned
+`@ubjs/node` N-API runtime. Upstream `0.31.0-3` returns Rust-owned memory through
+external ArrayBuffers, which Electron 20 and newer intentionally reject because
+of V8's memory cage. The copy-mode runtime keeps the generated UniFFI API and
+RustBuffer ownership contract unchanged, but copies at the native/JavaScript
+boundary before freeing Rust-owned return buffers. Regular Node and Electron
+therefore receive the same values; Electron hosts do not need to spawn or
+configure the private daemon themselves.
diff --git a/libs/cua-driver/typescript/package-lock.json b/libs/cua-driver/typescript/package-lock.json
index 791243386e..cb02a1f9fd 100644
--- a/libs/cua-driver/typescript/package-lock.json
+++ b/libs/cua-driver/typescript/package-lock.json
@@ -18,10 +18,42 @@
},
"devDependencies": {
"@types/node": "^22.0.0",
+ "electron": "43.2.0",
"typescript": "^5.7.0",
"uniffi-bindgen-react-native": "0.31.0-3"
}
},
+ "node_modules/@electron-internal/extract-zip": {
+ "version": "1.0.4",
+ "resolved": "https://registry.npmjs.org/@electron-internal/extract-zip/-/extract-zip-1.0.4.tgz",
+ "integrity": "sha512-Zr1Vs7E9tpCNhZHDAbFVXc2gEVCG9RqPDjrno5+bdgB6LRAuvgyMHJut4NCVyYwtAieapMzc3fiQ3CSTi75ARg==",
+ "dev": true,
+ "license": "BSD-2-Clause",
+ "engines": {
+ "node": ">=22.12.0"
+ }
+ },
+ "node_modules/@electron/get": {
+ "version": "5.0.0",
+ "resolved": "https://registry.npmjs.org/@electron/get/-/get-5.0.0.tgz",
+ "integrity": "sha512-pjoBpru1KdEtcExBnuHAP1cAc/5faoedw0hzJkL3o4/IJp7HNF1+fbrdxT3gMYRX2oJfvnA/WXeCTVQpYYxyJA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "debug": "^4.1.1",
+ "env-paths": "^3.0.0",
+ "graceful-fs": "^4.2.11",
+ "progress": "^2.0.3",
+ "semver": "^7.6.3",
+ "sumchecker": "^3.0.1"
+ },
+ "engines": {
+ "node": ">=22.12.0"
+ },
+ "optionalDependencies": {
+ "undici": "^7.24.4"
+ }
+ },
"node_modules/@types/node": {
"version": "22.20.1",
"resolved": "https://registry.npmjs.org/@types/node/-/node-22.20.1.tgz",
@@ -158,6 +190,123 @@
"win32"
]
},
+ "node_modules/debug": {
+ "version": "4.4.3",
+ "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+ "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "ms": "^2.1.3"
+ },
+ "engines": {
+ "node": ">=6.0"
+ },
+ "peerDependenciesMeta": {
+ "supports-color": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/electron": {
+ "version": "43.2.0",
+ "resolved": "https://registry.npmjs.org/electron/-/electron-43.2.0.tgz",
+ "integrity": "sha512-80zvrgG7ZRXD+tD0IyLvrnN9n+veSxadMRsMaC9wKKP3iUbtC7rGM8+dVuCmOb0Rrwwv8ESW4awnUZh9Hbp1fA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@electron-internal/extract-zip": "^1.0.1",
+ "@electron/get": "^5.0.0",
+ "@types/node": "^24.9.0"
+ },
+ "bin": {
+ "electron": "cli.js",
+ "install-electron": "install.js"
+ },
+ "engines": {
+ "node": ">= 22.12.0"
+ }
+ },
+ "node_modules/electron/node_modules/@types/node": {
+ "version": "24.13.3",
+ "resolved": "https://registry.npmjs.org/@types/node/-/node-24.13.3.tgz",
+ "integrity": "sha512-Dh8vAsV36ig5wa9OX4pXvMc9D3Veibfw2wix0CUwYODLD8nkj9UsLjASr49nPg+2eKzxhBV+v7L8pXvT4e639Q==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "undici-types": "~7.18.0"
+ }
+ },
+ "node_modules/electron/node_modules/undici-types": {
+ "version": "7.18.2",
+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz",
+ "integrity": "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/env-paths": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/env-paths/-/env-paths-3.0.0.tgz",
+ "integrity": "sha512-dtJUTepzMW3Lm/NPxRf3wP4642UWhjL2sQxc+ym2YMj1m/H2zDNQOlezafzkHwn6sMstjHTwG6iQQsctDW/b1A==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
+ "node_modules/graceful-fs": {
+ "version": "4.2.11",
+ "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
+ "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
+ "dev": true,
+ "license": "ISC"
+ },
+ "node_modules/ms": {
+ "version": "2.1.3",
+ "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+ "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/progress": {
+ "version": "2.0.3",
+ "resolved": "https://registry.npmjs.org/progress/-/progress-2.0.3.tgz",
+ "integrity": "sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.4.0"
+ }
+ },
+ "node_modules/semver": {
+ "version": "7.8.5",
+ "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
+ "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
+ "dev": true,
+ "license": "ISC",
+ "bin": {
+ "semver": "bin/semver.js"
+ },
+ "engines": {
+ "node": ">=10"
+ }
+ },
+ "node_modules/sumchecker": {
+ "version": "3.0.1",
+ "resolved": "https://registry.npmjs.org/sumchecker/-/sumchecker-3.0.1.tgz",
+ "integrity": "sha512-MvjXzkz/BOfyVDkG0oFOtBxHX2u3gKbMHIF/dXblZsgD3BWOFLmHovIpZY7BykJdAjcqRCBi1WYBNdEC9yI7vg==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "debug": "^4.1.0"
+ },
+ "engines": {
+ "node": ">= 8.0"
+ }
+ },
"node_modules/typescript": {
"version": "5.9.3",
"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
@@ -172,6 +321,17 @@
"node": ">=14.17"
}
},
+ "node_modules/undici": {
+ "version": "7.28.0",
+ "resolved": "https://registry.npmjs.org/undici/-/undici-7.28.0.tgz",
+ "integrity": "sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA==",
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "engines": {
+ "node": ">=20.18.1"
+ }
+ },
"node_modules/undici-types": {
"version": "6.21.0",
"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
diff --git a/libs/cua-driver/typescript/package.json b/libs/cua-driver/typescript/package.json
index 3d7fff67b2..32a87ec8f2 100644
--- a/libs/cua-driver/typescript/package.json
+++ b/libs/cua-driver/typescript/package.json
@@ -48,6 +48,7 @@
},
"devDependencies": {
"@types/node": "^22.0.0",
+ "electron": "43.2.0",
"typescript": "^5.7.0",
"uniffi-bindgen-react-native": "0.31.0-3"
},
diff --git a/libs/cua-driver/typescript/src/native/cua_driver_contract-ffi.ts b/libs/cua-driver/typescript/src/native/cua_driver_contract-ffi.ts
index 90dee1d78a..df95260a99 100644
--- a/libs/cua-driver/typescript/src/native/cua_driver_contract-ffi.ts
+++ b/libs/cua-driver/typescript/src/native/cua_driver_contract-ffi.ts
@@ -4,7 +4,7 @@
/* eslint-disable */
// @ts-nocheck
-import lib from "@ubjs/node";
+import lib from "./node-runtime.js";
const { UniffiNativeModule, FfiType, resolveLibPath } = lib;
import {
diff --git a/libs/cua-driver/typescript/src/native/cua_driver_sdk-ffi.ts b/libs/cua-driver/typescript/src/native/cua_driver_sdk-ffi.ts
index a61876bb25..3299e85628 100644
--- a/libs/cua-driver/typescript/src/native/cua_driver_sdk-ffi.ts
+++ b/libs/cua-driver/typescript/src/native/cua_driver_sdk-ffi.ts
@@ -4,7 +4,7 @@
/* eslint-disable */
// @ts-nocheck
-import lib from "@ubjs/node";
+import lib from "./node-runtime.js";
const { UniffiNativeModule, FfiType, resolveLibPath } = lib;
import {
diff --git a/libs/cua-driver/typescript/src/native/node-runtime.ts b/libs/cua-driver/typescript/src/native/node-runtime.ts
new file mode 100644
index 0000000000..4c04226d99
--- /dev/null
+++ b/libs/cua-driver/typescript/src/native/node-runtime.ts
@@ -0,0 +1,42 @@
+import { createRequire } from "node:module"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { resolveLibPath } from "@ubjs/node/typescript/dist/resolve-lib.js"
+
+const FfiType = {
+ UInt8: { tag: "UInt8" },
+ Int8: { tag: "Int8" },
+ UInt16: { tag: "UInt16" },
+ Int16: { tag: "Int16" },
+ UInt32: { tag: "UInt32" },
+ Int32: { tag: "Int32" },
+ UInt64: { tag: "UInt64" },
+ Int64: { tag: "Int64" },
+ Float32: { tag: "Float32" },
+ Float64: { tag: "Float64" },
+ Handle: { tag: "Handle" },
+ RustBuffer: { tag: "RustBuffer" },
+ ForeignBytes: { tag: "ForeignBytes" },
+ RustCallStatus: { tag: "RustCallStatus" },
+ VoidPointer: { tag: "VoidPointer" },
+ Void: { tag: "Void" },
+ Callback: (name: string) => ({ tag: "Callback", name }),
+ Struct: (name: string) => ({ tag: "Struct", name }),
+ Reference: (inner: unknown) => ({ tag: "Reference", inner }),
+ MutReference: (inner: unknown) => ({ tag: "MutReference", inner }),
+}
+
+const sdkLibrary = resolveLibPath({
+ crateName: "cua_driver_sdk",
+ callerUrl: import.meta.url,
+ npmPackageBase: "@trycua/cua-driver-",
+ tripleStyle: "node",
+})
+const runtimePath = join(dirname(sdkLibrary), "cua_driver_node_runtime.node")
+const require = createRequire(import.meta.url)
+const { UniffiNativeModule } = require(runtimePath) as {
+ UniffiNativeModule: unknown
+}
+
+export default { FfiType, resolveLibPath, UniffiNativeModule }
diff --git a/libs/cua-driver/typescript/test/electron-main-fixture.mjs b/libs/cua-driver/typescript/test/electron-main-fixture.mjs
new file mode 100644
index 0000000000..5033c67121
--- /dev/null
+++ b/libs/cua-driver/typescript/test/electron-main-fixture.mjs
@@ -0,0 +1,127 @@
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+const directory = mkdtempSync(path.join(os.tmpdir(), "cua-driver-electron-host-"))
+const binaryPath = path.join(directory, "generic-driver-host")
+
+writeFileSync(
+ binaryPath,
+ `#!/usr/bin/env node
+const fs = require("node:fs");
+const net = require("node:net");
+const path = require("node:path");
+const args = process.argv.slice(2);
+const socketPath = args[args.indexOf("--socket") + 1];
+const hostBundleId = args[args.indexOf("--host-bundle-id") + 1];
+fs.writeFileSync(path.join(path.dirname(process.argv[1]), hostBundleId + ".pid"), String(process.pid));
+const server = net.createServer(socket => {
+ let buffer = "";
+ socket.setEncoding("utf8");
+ socket.on("data", chunk => {
+ buffer += chunk;
+ if (!buffer.includes("\\n")) return;
+ const request = JSON.parse(buffer.split("\\n", 1)[0]);
+ const result = request.method === "metadata" ? {
+ driver_version: "0.11.0",
+ contract_version: hostBundleId.endsWith(".failure") ? "incompatible" : "0.2.0",
+ tools_list_schema_version: "1",
+ capability_version: "1",
+ mcp_protocol_version: "2025-06-18",
+ pid: process.pid,
+ embedded: true,
+ host_bundle_id: hostBundleId,
+ } : { tools: [{ name: "electron_fixture" }] };
+ socket.end(JSON.stringify({ ok: true, result }) + "\\n");
+ });
+});
+server.listen(socketPath, () => fs.chmodSync(socketPath, 0o600));
+process.stdin.resume();
+process.stdin.on("end", () => server.close(() => process.exit(0)));
+`,
+)
+chmodSync(binaryPath, 0o755)
+
+const processExists = (pid) => {
+ try {
+ process.kill(pid, 0)
+ return true
+ } catch (error) {
+ if (error?.code === "ESRCH") return false
+ throw error
+ }
+}
+
+const waitForExit = async (pid) => {
+ for (let attempt = 0; attempt < 40; attempt += 1) {
+ if (!processExists(pid)) return true
+ await new Promise((resolve) => setTimeout(resolve, 25))
+ }
+ return !processExists(pid)
+}
+
+try {
+ const { EmbeddedCuaDriverHost, EmbeddedDriverHostState } = await import(
+ "@trycua/cua-driver/embedded"
+ )
+ const host = new EmbeddedCuaDriverHost(binaryPath, "com.example.electron-host")
+ const connection = await host.start()
+ const socketPath = connection.socketPath
+ const pid = connection.pid
+ const { CuaDriver } = await import("@trycua/cua-driver")
+ const driver = CuaDriver.connect(socketPath)
+ const tools = JSON.parse(driver.listToolsJson())
+ driver.uniffiDestroy()
+ const result = {
+ versions: {
+ electron: process.versions.electron,
+ node: process.versions.node,
+ package: JSON.parse(
+ readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+ ).version,
+ },
+ connection: {
+ socketPathIsPrivate:
+ socketPath.startsWith(os.tmpdir()) && path.basename(socketPath).startsWith("cua-"),
+ pidMatchesChild: Number(readFileSync(path.join(directory, "com.example.electron-host.pid"), "utf8")) === pid,
+ stateIsReady: host.state() === EmbeddedDriverHostState.Ready,
+ mcpCommand: connection.mcp.command,
+ mcpArgs: connection.mcp.args,
+ tools,
+ },
+ }
+ await host.stop()
+ host.uniffiDestroy()
+ result.cleanup = {
+ socketRemoved: !existsSync(socketPath),
+ childExited: await waitForExit(pid),
+ }
+
+ const failingHost = new EmbeddedCuaDriverHost(binaryPath, "com.example.electron-host.failure")
+ let failureCode
+ try {
+ await failingHost.start()
+ } catch (error) {
+ failureCode = error?.inner?.reason ?? error?.message
+ }
+ const failurePid = Number(
+ readFileSync(path.join(directory, "com.example.electron-host.failure.pid"), "utf8"),
+ )
+ const failedSocket = failingHost.connection()?.socketPath
+ result.failureCleanup = {
+ rejected: typeof failureCode === "string" && failureCode.length > 0,
+ stateIsStopped: failingHost.state() === EmbeddedDriverHostState.Stopped,
+ socketRemoved: failedSocket === undefined || !existsSync(failedSocket),
+ childExited: await waitForExit(failurePid),
+ }
+ await failingHost.stop()
+ failingHost.uniffiDestroy()
+ process.stdout.write(`${JSON.stringify(result)}\n`)
+} catch (error) {
+ process.stderr.write(`${error?.stack ?? error}\n`)
+ process.exitCode = 1
+} finally {
+ rmSync(directory, { recursive: true, force: true })
+}
+
+process.exit(process.exitCode ?? 0)
diff --git a/libs/cua-driver/typescript/test/electron-main.test.mjs b/libs/cua-driver/typescript/test/electron-main.test.mjs
new file mode 100644
index 0000000000..27caeeba46
--- /dev/null
+++ b/libs/cua-driver/typescript/test/electron-main.test.mjs
@@ -0,0 +1,48 @@
+import assert from "node:assert/strict"
+import { spawn } from "node:child_process"
+import { existsSync } from "node:fs"
+import path from "node:path"
+import test from "node:test"
+import { fileURLToPath } from "node:url"
+
+const testDirectory = path.dirname(fileURLToPath(import.meta.url))
+const electron = path.resolve(testDirectory, "../node_modules/.bin/electron")
+
+test(
+ "Electron main receives embedded connection values and cleans up lifecycle",
+ { skip: process.platform === "win32" || !existsSync(electron), timeout: 60_000 },
+ async () => {
+ const command = process.platform === "linux" ? "xvfb-run" : electron
+ const args = process.platform === "linux"
+ ? ["-a", electron, path.join(testDirectory, "electron-main-fixture.mjs")]
+ : [path.join(testDirectory, "electron-main-fixture.mjs")]
+ const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] })
+ let stdout = ""
+ let stderr = ""
+ child.stdout.setEncoding("utf8").on("data", (chunk) => { stdout += chunk })
+ child.stderr.setEncoding("utf8").on("data", (chunk) => { stderr += chunk })
+ const code = await new Promise((resolve, reject) => {
+ child.on("error", reject)
+ child.on("exit", resolve)
+ })
+
+ assert.equal(code, 0, stderr)
+ const result = JSON.parse(stdout.trim().split("\n").at(-1))
+ assert.equal(result.versions.electron, "43.2.0")
+ assert.equal(result.versions.package, "0.11.0")
+ assert.equal(result.connection.socketPathIsPrivate, true)
+ assert.equal(result.connection.pidMatchesChild, true)
+ assert.equal(result.connection.stateIsReady, true)
+ assert.equal(result.connection.mcpCommand.endsWith("generic-driver-host"), true)
+ assert.equal(result.connection.mcpArgs.includes("mcp"), true)
+ assert.equal(result.connection.mcpArgs.includes("--embedded"), true)
+ assert.deepEqual(result.connection.tools, { tools: [{ name: "electron_fixture" }] })
+ assert.deepEqual(result.cleanup, { socketRemoved: true, childExited: true })
+ assert.deepEqual(result.failureCleanup, {
+ rejected: true,
+ stateIsStopped: true,
+ socketRemoved: true,
+ childExited: true,
+ })
+ },
+)