feat(desktop): add opt-in cua-driver computer use

[injaneity]

what changed

adds opt-in computer use to the macos, linux, and windows desktop apps. when enabled, desktop passes the packaged cua-driver path and embedded module configuration to its local node server. the existing scoped embedded host owns the driver process and exposes its tools to codex.

packaged builds now download checksum-pinned driver assets for each supported platform and architecture. macos and linux use their release tarballs. windows uses its release zip and powershell expand-archive, which avoids incompatible gnu tar installations earlier on path.

macos keeps its existing permission-inheritance behavior. linux and windows need no additional permission-inheritance implementation and reuse the same embedded lifecycle without installing services, autostart entries, or persistent daemons.

why

the embedded host gives all three platforms one process-ownership model: t3 code starts the driver only after the user opts in, and the scoped finalizer stops it with the server. platform-specific code is limited to release assets, extraction, and executable paths.

validation

• local: 43 focused tests, affected package typechecks, lint, and formatting pass.
• cua-linux: 43 focused tests pass; checksum, extraction, binary execution, embedded startup, and clean shutdown pass.
• cua-windows: 43 focused tests and affected package typechecks pass; checksum, powershell extraction, binary execution, embedded startup, and clean shutdown pass.
• the windows remote runs in session 0, so gui interaction remains subject to the driver’s documented interactive-session requirement.

ui changes

the existing computer-use setting now appears on every supported desktop platform.

checklist

• this pr is small and focused
• i explained what changed and why
• i included before/after screenshots for ui changes
• i tested the platform-specific paths on linux and windows hosts

Note

Add opt-in embedded cua-driver computer use to the desktop app

• Adds an enableCua toggle to client settings (default false) exposed in the desktop General Settings panel; the feature is only shown when the desktop bridge is available.
• On startup, DesktopApp reads enableCua and calls configureCuaDriverServerEnvironment to set cua-related process env vars (T3CODE_CUA_DRIVER_PATH, T3CODE_CUA_DRIVER_HOST_BUNDLE_ID, T3CODE_CUA_DRIVER_MODULE_URL); on failure, it shows a blocking error dialog and continues with cua disabled.
• Server startup gains a cua-driver.start phase via startEmbeddedCuaDriver, which imports the driver module by URL, starts the host, installs Codex MCP launch args via T3CODE_CODEX_APPEND_LAUNCH_ARGS_ENV, and monitors the driver process; it cleans up on scope shutdown.
• The desktop build script now downloads, SHA-256 verifies, extracts, and stages the @trycua/cua-driver (v0.12.2) binary for the target platform/arch into prod-resources/cua-driver, then includes it as an Electron extra resource.
• Risk: the cua-driver binary is fetched at build time from a pinned release URL; a checksum mismatch surfaces as CuaDriverChecksumMismatchError and fails the build.

^{Macroscope summarized 4d2f83e.}

---

Note

Medium Risk
Opt-in feature with scoped driver lifecycle, but it runs a native host, mutates process env for Codex MCP, and enables agents to control the user's machine when turned on.

Overview
Adds opt-in computer use for desktop (macOS, Linux, Windows) via @trycua/cua-driver 0.12.2, default off.

Settings & UI: New enableCua on client settings (contracts + General settings when desktopBridge is present). Users must restart after toggling.

Desktop startup: If enabled, configureCuaDriverServerEnvironment sets T3CODE_CUA_DRIVER_* for the local Node server (packaged driver path, host bundle id, embedded module URL). Inherited env vars are cleared when disabled so dev overrides cannot bypass opt-in. Configuration failures show an error dialog and the app continues without computer use.

Server: startEmbeddedCuaDriver starts the embedded host when env is set, wires Codex MCP via T3CODE_CODEX_APPEND_LAUNCH_ARGS, and tears down on driver exit. Codex adapter spawn args prefer live append launch args over stale per-session env snapshots.

Packaging: Desktop artifact build downloads checksum-pinned release binaries per platform/arch, stages them into prod-resources/cua-driver, and includes them in extraResources.

^{Reviewed by Cursor Bugbot for commit 4d2f83e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[macroscopeapp]

Effect service conventions review: one error-modeling issue found in the new Cua modules. Everything else (namespace imports from effect/*, Schema.TaggedErrorClass usage, scoped finalizers, Path.Path acquired from the environment, whole-channel Effect.catch) matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One convention finding on the new Cua driver error definitions. See the inline comment.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Effect service conventions review: two findings on error context and tagged-failure recovery in the new Cua driver modules.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Effect service conventions review: one error-context finding in apps/server/src/cua/CuaDriverEmbedded.ts.

^{Posted via Macroscope — Effect Service Conventions}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit d296a0d. Configure here.}