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.

feat(spaces): permissions step in the new first run, one permission flow with the Cua Driver page (CUA-3550) (#6579)

Francesco Bonacci0f7a3846b190
diff --git a/apps/cua-spaces-desktop/src/bridge/driver.ts b/apps/cua-spaces-desktop/src/bridge/driver.ts
index 0345726dc5..1686698fac 100644
--- a/apps/cua-spaces-desktop/src/bridge/driver.ts
+++ b/apps/cua-spaces-desktop/src/bridge/driver.ts
@@ -25,5 +25,7 @@ export function driverMethods(_ctx: BridgeContext): Handlers {
"driver.pause": no,
"driver.setup": no,
"driver.setApp": no,
+ // Cua Spaces asks for no screen or input permission here.
+ "driver.permissions": () => null,
};
}
diff --git a/apps/cua-spaces-desktop/src/bridge/methods.ts b/apps/cua-spaces-desktop/src/bridge/methods.ts
index c86e60fecc..88d9fbfd65 100644
--- a/apps/cua-spaces-desktop/src/bridge/methods.ts
+++ b/apps/cua-spaces-desktop/src/bridge/methods.ts
@@ -63,7 +63,7 @@ export const METHODS = [
"thread.agentAdd", "thread.agentRemove",
"thread.joinCodeCreate", "thread.joinCodeList", "thread.joinCodeCancel", "thread.settings",
"driver.status", "driver.list", "driver.config", "driver.setConfig", "driver.test", "driver.pause",
- "driver.setup", "driver.setApp",
+ "driver.setup", "driver.setApp", "driver.permissions",
] as const;
/** A live desktop's media ticket for the page's WebCodecs player,
diff --git a/apps/cua-spaces-desktop/test/bridge-native.test.ts b/apps/cua-spaces-desktop/test/bridge-native.test.ts
index a2415fe617..0176cf1038 100644
--- a/apps/cua-spaces-desktop/test/bridge-native.test.ts
+++ b/apps/cua-spaces-desktop/test/bridge-native.test.ts
@@ -214,7 +214,7 @@ describe.skipIf(!built)("the bridge on the app core", () => {
// Every ported method has its case (or is checked below).
// (Teleport and the Keyvault: vault-native.test.ts; This machine, Devices, Settings and the rest: host-bridge.test.ts; the relay allowance: relay-usage.test.ts; resource numbers: resources.test.ts; presence: presence-bridge.test.ts; the Machines page's rename, remove and health checks, and the default Space: machines-view.test.ts; the Windows runtime fix: below.)
// (The CI Runners methods, ci.*: ci.test.ts. They run the bundled `cua`, which this core-only test does not have.)
- const elsewhere = new Set(["ci.overview", "ci.connect", "ci.connectToken", "ci.connectCancel", "ci.repositories", "ci.goal", "ci.log", "session.signIn", "spaces.create", "spaces.delete", "spaces.openStream", "relay.usage", "sharing.removals", "sharing.ackRemovals", "resources.get", "machines.rename", "machines.remove", "machines.checkHealth", "spaces.settings", "spaces.setSettings", "spaces.resolveDefault", "presence.join", "presence.publish", "presence.leave", "spaces.fixRuntime", "cli.install", "runtimes.check", "runtimes.browse", "repoCache.get", "repoCache.set", "repoCache.clear", "driver.status", "driver.list", "driver.config", "driver.setConfig", "driver.test", "driver.pause", "driver.setup", "driver.setApp", ...THREAD_OPERATIONS, ...AGENT_METHODS, ...VAULT_METHODS, ...HOST_METHODS]);
+ const elsewhere = new Set(["ci.overview", "ci.connect", "ci.connectToken", "ci.connectCancel", "ci.repositories", "ci.goal", "ci.log", "session.signIn", "spaces.create", "spaces.delete", "spaces.openStream", "relay.usage", "sharing.removals", "sharing.ackRemovals", "resources.get", "machines.rename", "machines.remove", "machines.checkHealth", "spaces.settings", "spaces.setSettings", "spaces.resolveDefault", "presence.join", "presence.publish", "presence.leave", "spaces.fixRuntime", "cli.install", "runtimes.check", "runtimes.browse", "repoCache.get", "repoCache.set", "repoCache.clear", "driver.status", "driver.list", "driver.config", "driver.setConfig", "driver.test", "driver.pause", "driver.setup", "driver.setApp", "driver.permissions", ...THREAD_OPERATIONS, ...AGENT_METHODS, ...VAULT_METHODS, ...HOST_METHODS]);
const ported = bridge.registry.methods.filter((m) => !NOT_YET.includes(m) && !elsewhere.has(m));
expect(ported.filter((m) => !cases.some(([c]) => c === m))).toEqual([]);
});
@@ -661,7 +661,7 @@ describe.skipIf(!built)("the bridge on the app core", () => {
// This machine, Devices, Settings and the rest: host-bridge.test.ts reads them with their arguments (the Machines page's rename and remove: machines-view.test.ts).
// (The CI Runners methods, ci.*: ci.test.ts. They run the bundled `cua`, which this core-only test does not have.)
// (The Cua Driver page, driver.*: the Electron app has no driver and refuses with "comes with the Mac app".)
- const skip = new Set<OpName>(["driver.status", "driver.list", "driver.config", "driver.setConfig", "driver.test", "driver.pause", "driver.setup", "driver.setApp", "ci.overview", "ci.connect", "ci.connectToken", "ci.connectCancel", "ci.repositories", "ci.goal", "ci.log", "spaces.create", "spaces.delete", "session.signIn", "session.signOut", "session.openExternal", "spaces.openStream", "relay.usage", "sharing.removals", "sharing.ackRemovals", "resources.get", "machines.rename", "machines.remove", "machines.checkHealth", "spaces.settings", "spaces.setSettings", "spaces.resolveDefault", "presence.join", "presence.publish", "presence.leave", "spaces.fixRuntime", "cli.install", "runtimes.check", "runtimes.browse", "repoCache.get", "repoCache.set", "repoCache.clear", ...(THREAD_OPERATIONS as readonly string[] as OpName[]), ...VAULT_OPS, ...(HOST_OPS as OpName[])]);
+ const skip = new Set<OpName>(["driver.status", "driver.list", "driver.config", "driver.setConfig", "driver.test", "driver.pause", "driver.setup", "driver.setApp", "driver.permissions", "ci.overview", "ci.connect", "ci.connectToken", "ci.connectCancel", "ci.repositories", "ci.goal", "ci.log", "spaces.create", "spaces.delete", "session.signIn", "session.signOut", "session.openExternal", "spaces.openStream", "relay.usage", "sharing.removals", "sharing.ackRemovals", "resources.get", "machines.rename", "machines.remove", "machines.checkHealth", "spaces.settings", "spaces.setSettings", "spaces.resolveDefault", "presence.join", "presence.publish", "presence.leave", "spaces.fixRuntime", "cli.install", "runtimes.check", "runtimes.browse", "repoCache.get", "repoCache.set", "repoCache.clear", ...(THREAD_OPERATIONS as readonly string[] as OpName[]), ...VAULT_OPS, ...(HOST_OPS as OpName[])]);
// (The thread: thread.test.ts.)
const problems: string[] = [];
const checked: string[] = [];
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/PermissionGuide.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/PermissionGuide.swift
index 4343ec77f6..4eac8a05ad 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/PermissionGuide.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/PermissionGuide.swift
@@ -250,6 +250,9 @@ public enum PermissionGuide {
/// `CuaSpacesMac preflight-permissions` in a new process: the guided
/// panes macOS has granted this app.
nonisolated static func freshProcessGrants() -> Set<PermissionFlowPane> {
+ // Not running as an app (tests, `swift run`): this process is the
+ // one macOS answers for, and there is no app to start a copy of.
+ guard Bundle.main.bundleURL.pathExtension == "app" else { return parseGrants(preflightReport()) }
guard let exe = Bundle.main.executableURL else { return [] }
let p = Process()
p.executableURL = exe
@@ -386,6 +389,27 @@ public enum PermissionGuide {
NSApp.windows.first { $0.isVisible && $0.canBecomeMain }?.makeKeyAndOrderFront(nil)
}
+ /// The name System Settings lists this app under: "Cua Spaces", or
+ /// "Cua Spaces Local" for the Local build, which has its own bundle id
+ /// and so its own grants.
+ nonisolated static func appName(info: [String: Any]? = Bundle.main.infoDictionary) -> String {
+ for key in ["CFBundleDisplayName", "CFBundleName"] {
+ if let name = info?[key] as? String, !name.isEmpty { return name }
+ }
+ return "Cua Spaces"
+ }
+
+ /// The two guided permissions as the pages read them (`AppPermission`
+ /// in the web's `ops/driver.ts`): `screen` and `accessibility`, each
+ /// granted or not, with its System Settings pane.
+ nonisolated static func rows(granted: Set<PermissionFlowPane>) -> [[String: Any]] {
+ let panes: [(String, PermissionFlowPane)] = [("screen", .screenRecording), ("accessibility", .accessibility)]
+ return panes.map { id, pane -> [String: Any] in
+ let url: Any = settingsURL(for: pane).map { $0 as Any } ?? NSNull()
+ return ["id": id, "granted": granted.contains(pane), "settingsUrl": url]
+ }
+ }
+
nonisolated static func settingsURL(for pane: PermissionFlowPane) -> String? {
switch pane {
case .screenRecording: "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge+Driver.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge+Driver.swift
index ebf324be1b..7fdc5108dc 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge+Driver.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge+Driver.swift
@@ -32,6 +32,8 @@ extension WebUIBridge {
throw Failure.unsupported("Open Cua Spaces on that computer to see its Cua Driver")
}
switch method {
+ case "driver.permissions":
+ return await appPermissions()
case "driver.status":
guard let driver = EmbeddedDriver.current() else { return NSNull() }
return await driverStatus(driver)
@@ -101,6 +103,21 @@ extension WebUIBridge {
}
}
+ /// `AppPermissions`: Cua Spaces' own Screen Recording and Accessibility,
+ /// the grants Cua Driver uses (it runs as Cua Spaces' child, so macOS
+ /// never lists it on its own). Answered on any Mac, with or without a
+ /// driver, for the first run's permissions step, the Driver page and
+ /// This Mac. Once both are on, a running driver that still says no (it
+ /// keeps the Screen Recording answer it had at launch) starts again,
+ /// once.
+ func appPermissions() async -> [String: Any] {
+ let granted = await PermissionGuide.readGranted()
+ if granted.contains(.screenRecording), granted.contains(.accessibility), let driver = EmbeddedDriver.current() {
+ await restartDriverIfStale(driver, force: false)
+ }
+ return ["appName": PermissionGuide.appName(), "permissions": PermissionGuide.rows(granted: granted)]
+ }
+
/// `DriverStatus`.
func driverStatus(_ driver: EmbeddedDriver) async -> [String: Any] {
let paused = FileManager.default.fileExists(atPath: driver.pausedMarker)
@@ -137,10 +154,8 @@ extension WebUIBridge {
"update": NSNull(),
"lastTest": orNull(DriverPageState.shared.lastTest),
"lastError": orNull(lastError),
- "permissions": [
- ["id": "screen", "granted": screen, "settingsUrl": orNull(PermissionGuide.settingsURL(for: .screenRecording))],
- ["id": "accessibility", "granted": accessibility, "settingsUrl": orNull(PermissionGuide.settingsURL(for: .accessibility))],
- ],
+ "permissions": PermissionGuide.rows(granted: granted),
+ "appName": PermissionGuide.appName(),
"activity": [Any](),
"canPause": true,
]
@@ -200,7 +215,7 @@ extension WebUIBridge {
/// The driver keeps the Screen Recording answer it had when it started:
/// granted to Cua Spaces since, it still says no until it starts again.
/// cua-spacesd starts it again within a second when it exits.
- private func restartDriverIfStale(_ driver: EmbeddedDriver, force: Bool) async {
+ func restartDriverIfStale(_ driver: EmbeddedDriver, force: Bool) async {
let state = DriverPageState.shared
if !force, let last = state.lastRestart, Date().timeIntervalSince(last) < 60 { return }
let stale: Int32? = await Task.detached { () -> Int32? in
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge.swift
index 686fabb72f..178aa1a324 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge.swift
@@ -150,7 +150,7 @@ final class WebUIBridge: NSObject, WKScriptMessageHandlerWithReply {
"thread.joinCodeCreate", "thread.joinCodeList", "thread.joinCodeCancel", "thread.settings",
// Cua Driver inside Cua Spaces: the embedded driver's page (WebUIBridge+Driver.swift).
"driver.status", "driver.list", "driver.config", "driver.setConfig", "driver.test", "driver.pause",
- "driver.setup", "driver.setApp",
+ "driver.setup", "driver.setApp", "driver.permissions",
]
let model: AppModel
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/BridgeContractTests.swift b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/BridgeContractTests.swift
index 5440dbbe50..774bf277ca 100644
--- a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/BridgeContractTests.swift
+++ b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/BridgeContractTests.swift
@@ -341,6 +341,7 @@ struct BridgeContractTests {
("startup.get", [:]),
// A test runner carries no Cua Driver: null and an empty list.
("driver.status", [:]),
+ ("driver.permissions", [:]),
("driver.list", [:]),
]
}
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/PermissionGuideTests.swift b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/PermissionGuideTests.swift
index e4103ea1f6..627f22ad9c 100644
--- a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/PermissionGuideTests.swift
+++ b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/PermissionGuideTests.swift
@@ -33,6 +33,28 @@ struct PermissionGuideTests {
#expect(!PermissionGuide.needsReopen(after: .accessibility))
}
+ /// The first run's step, the Driver page and This Mac read the same two
+ /// rows (`driver.permissions`), each with the pane its Allow guides.
+ @Test func thePagesReadBothPermissionsWithTheirPanes() throws {
+ let rows = PermissionGuide.rows(granted: [.accessibility])
+ #expect(rows.map { $0["id"] as? String } == ["screen", "accessibility"])
+ #expect(rows.map { $0["granted"] as? Bool } == [false, true])
+ for row in rows {
+ let url = try #require(row["settingsUrl"] as? String)
+ #expect(PermissionGuide.pane(for: url) != nil)
+ }
+ #expect(PermissionGuide.rows(granted: []).allSatisfy { $0["granted"] as? Bool == false })
+ }
+
+ /// Cua Spaces Local has its own bundle id, so its own grants: the pages
+ /// name the app System Settings lists.
+ @Test func namesTheAppSystemSettingsLists() {
+ #expect(PermissionGuide.appName(info: ["CFBundleDisplayName": "Cua Spaces Local", "CFBundleName": "CuaSpacesMac"]) == "Cua Spaces Local")
+ #expect(PermissionGuide.appName(info: ["CFBundleName": "Cua Spaces"]) == "Cua Spaces")
+ #expect(PermissionGuide.appName(info: ["CFBundleDisplayName": ""]) == "Cua Spaces")
+ #expect(PermissionGuide.appName(info: nil) == "Cua Spaces")
+ }
+
@Test func everyGuidedPaneHasItsSettingsURL() {
for pane in PermissionGuide.guided {
let url = PermissionGuide.settingsURL(for: pane)
diff --git a/apps/cua-spaces-web/e2e/layout-anchors.spec.ts b/apps/cua-spaces-web/e2e/layout-anchors.spec.ts
index 2bb4fd6ef1..e3b0f6c9c4 100644
--- a/apps/cua-spaces-web/e2e/layout-anchors.spec.ts
+++ b/apps/cua-spaces-web/e2e/layout-anchors.spec.ts
@@ -89,6 +89,13 @@ for (const [width, height] of SIZES) {
await page.locator("[data-onboarding-later]").click();
await measure("where");
await primary.click();
+ // On a Mac host, Cua Spaces' permissions come next (CUA-3550): its button sits in the same pinned row.
+ await expect(root).toHaveAttribute("data-step", /^(permissions|agent)$/, { timeout: 30_000 });
+ if ((await root.getAttribute("data-step")) === "permissions") {
+ await page.locator("[data-new-run-permissions-next]").waitFor();
+ await measure("permissions", "[data-new-run-permissions-next]");
+ await primary.click();
+ }
await page.locator("[data-new-run='agent']:not([data-state='looking'])").waitFor({ timeout: 30_000 });
if (await primary.isDisabled()) await page.locator("[data-new-run-agent][role=checkbox]").first().click();
await measure("agent");
diff --git a/apps/cua-spaces-web/src/__tests__/first-run-new.test.tsx b/apps/cua-spaces-web/src/__tests__/first-run-new.test.tsx
index e456487200..16dace08ca 100644
--- a/apps/cua-spaces-web/src/__tests__/first-run-new.test.tsx
+++ b/apps/cua-spaces-web/src/__tests__/first-run-new.test.tsx
@@ -14,10 +14,12 @@ import { wasmBuilt } from "@/bridge/__tests__/testCore";
import type { AgentSetupRow } from "@/bridge/contracts/agents";
import { readFirstRun, resetFirstRunCache } from "@/bridge/first-run";
import { resetSavedOnboardingCache } from "@/bridge/onboarding";
-import { AgentScreen, NextScreen, ReadyScreen, SignInScreen, StepDots, WhereScreen } from "@/components/first-run-new/first-run-new";
+import { AgentScreen, NextScreen, PermissionsScreen, ReadyScreen, SignInScreen, StepDots, WhereScreen } from "@/components/first-run-new/first-run-new";
import { placeKeys } from "@/components/first-run-new/float-keys";
import { resetConnectedAppsState } from "@/hooks/use-connected-apps";
-import { agentView, chosenAgent, dotStep, nextView, reachedAfter, readyView, signInView, stepDots, togglePick, whereView, type WhereInput } from "@/lib/first-run-new";
+import type { AppPermissions } from "@/bridge/app-permissions";
+import { permissionsStepView } from "@/lib/app-permissions";
+import { afterWhere, agentView, chosenAgent, dotFor, dotStep, nextView, reachedAfter, readyView, signInView, stepDots, togglePick, whereView, type WhereInput } from "@/lib/first-run-new";
import { getDriver, resetPrepare } from "@/lib/prepare/store";
import { mountApp, stubBrowserApis } from "./app-harness";
@@ -297,6 +299,68 @@ describe("screen 4, Ready", () => {
});
});
+describe("2b, Cua Spaces' permissions (a Mac only)", () => {
+ const SCREEN = "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture";
+ const AX = "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility";
+ const data = (screen: boolean, accessibility: boolean, appName = "Cua Spaces"): AppPermissions => ({
+ appName,
+ permissions: [
+ { id: "screen", granted: screen, settingsUrl: SCREEN },
+ { id: "accessibility", granted: accessibility, settingsUrl: AX },
+ ],
+ });
+ const draw = (d: AppPermissions, allow = vi.fn(async () => {}), onContinue = vi.fn()) => {
+ const allGranted = d.permissions.every((p) => p.granted);
+ render(<PermissionsScreen view={permissionsStepView({ appName: d.appName, allGranted })} perms={{ data: d, allow }} onContinue={onContinue} />);
+ return { allow, onContinue };
+ };
+
+ it("comes after picking where agents work, on a Mac only, under the same dot", () => {
+ expect(afterWhere("macos")).toBe("permissions");
+ expect(afterWhere("windows")).toBe("agent");
+ expect(afterWhere("linux")).toBe("agent");
+ expect(dotFor("permissions")).toBe(dotFor("where"));
+ });
+
+ it("asks for both for Cua Spaces itself, says Cua Driver uses the same ones, and offers Later", () => {
+ const { allow, onContinue } = draw(data(false, false));
+ expect(screen.getByRole("heading").textContent).toBe("Let Cua Spaces see and use apps");
+ expect(text()).toContain("This lets your agents work in the apps on this Mac, in the background.");
+ expect(text()).toContain("Cua Driver uses these same permissions, so there's no second app to allow.");
+ const rows = [...document.querySelectorAll<HTMLElement>("[data-app-permission]")];
+ expect(rows.map((r) => r.dataset.appPermission)).toEqual(["screen", "accessibility"]);
+ expect(rows[0]!.textContent).toContain("See the screen");
+ expect(rows[0]!.textContent).toContain("Screen Recording, given to Cua Spaces");
+ expect(rows[1]!.textContent).toContain("Use the mouse and keyboard");
+ expect(rows[1]!.textContent).toContain("Accessibility, given to Cua Spaces");
+ fireEvent.click(rows[1]!.querySelector("button")!);
+ expect(allow).toHaveBeenCalledWith("accessibility");
+ // Never blocks: Later goes on.
+ const later = screen.getByRole("button", { name: "Later" });
+ fireEvent.click(later);
+ expect(onContinue).toHaveBeenCalled();
+ });
+
+ it("shows a grant as Allowed, and Continue once both are on", () => {
+ draw(data(true, false));
+ expect(document.querySelector("[data-app-permission=screen]")!.textContent).toContain("Allowed");
+ expect(document.querySelector("[data-app-permission=screen] button")).toBeNull();
+ expect(screen.getByRole("button", { name: "Later" })).toBeTruthy();
+ cleanup();
+ draw(data(true, true));
+ expect(screen.queryByRole("button", { name: "Allow" })).toBeNull();
+ expect(screen.getByRole("button", { name: "Continue" })).toBeTruthy();
+ expect(text()).toContain("Both are on.");
+ });
+
+ it("names Cua Spaces Local in the Local build, which has its own grants", () => {
+ draw(data(false, false, "Cua Spaces Local"));
+ expect(screen.getByRole("heading").textContent).toBe("Let Cua Spaces Local see and use apps");
+ expect(document.querySelector("[data-app-permission=screen]")!.textContent).toContain("Screen Recording, given to Cua Spaces Local");
+ expect(text()).toContain("Turn on Cua Spaces Local there, then come back.");
+ });
+});
+
describe("screen 6, next steps", () => {
it("offers to invite a teammate, add another computer and let agents use apps on this Mac", () => {
const onRow = vi.fn();
@@ -413,6 +477,11 @@ describe.skipIf(!wasmBuilt)("the new first run on its route", () => {
await waitFor(() => expect(heading()).toBe("Pick where your agents work"));
expect(document.querySelector("[data-new-run-this-status]")!.textContent).toBe("not added yet");
click("[data-onboarding-primary]");
+ // On a Mac, Cua Spaces' permissions next: both missing here, so Later goes on without them.
+ await waitFor(() => expect(heading()).toBe("Let Cua Spaces see and use apps"), { timeout: 15_000 });
+ await waitFor(() => expect(document.querySelectorAll("[data-app-permission]").length).toBe(2));
+ expect(calls.some((c) => c.op === "driver.permissions")).toBe(true);
+ click("[data-new-run-permissions-next=Later]");
await waitFor(() => expect(heading()).toBe("Your agents will use Codex"), { timeout: 15_000 });
click("[data-onboarding-primary]");
await waitFor(() => expect(heading()).toBe("Codex can now use this Mac"), { timeout: 15_000 });
diff --git a/apps/cua-spaces-web/src/__tests__/onboarding-lands-on-home.test.tsx b/apps/cua-spaces-web/src/__tests__/onboarding-lands-on-home.test.tsx
index 83797fcde5..b62f99eacb 100644
--- a/apps/cua-spaces-web/src/__tests__/onboarding-lands-on-home.test.tsx
+++ b/apps/cua-spaces-web/src/__tests__/onboarding-lands-on-home.test.tsx
@@ -48,6 +48,9 @@ async function throughOnboarding(hold?: Promise<void>) {
click("[data-onboarding-later]");
await waitFor(() => expect(heading()).toBe("Pick where your agents work"));
click("[data-onboarding-primary]");
+ // On a Mac, Cua Spaces' permissions come next (CUA-3550); a person can go on without them.
+ await waitFor(() => expect(document.querySelector("[data-new-run=permissions], [data-new-run=agent]")).not.toBeNull(), { timeout: 15_000 });
+ if (document.querySelector("[data-new-run=permissions]")) click("[data-onboarding-primary]");
await waitFor(() => expect(document.querySelector("[data-new-run=agent]:not([data-state=looking])")).not.toBeNull(), { timeout: 15_000 });
const several = document.querySelector("[data-new-run=agent][data-state=several]");
if (several) click("[data-new-run-agent=claude-code]");
diff --git a/apps/cua-spaces-web/src/bridge/__tests__/contract-args.ts b/apps/cua-spaces-web/src/bridge/__tests__/contract-args.ts
index 93837d606e..2d06993b8f 100644
--- a/apps/cua-spaces-web/src/bridge/__tests__/contract-args.ts
+++ b/apps/cua-spaces-web/src/bridge/__tests__/contract-args.ts
@@ -248,6 +248,7 @@ export const DEMO_ARGS: { [K in OpName]: OpArgs<K> } = {
"driver.setApp": { app: "codex", on: true },
"driver.setup": {},
"driver.update": {},
+ "driver.permissions": {},
};
/** Operations the demo host refuses on purpose, and why. */
diff --git a/apps/cua-spaces-web/src/bridge/adapters/demo/driver.ts b/apps/cua-spaces-web/src/bridge/adapters/demo/driver.ts
index 538c63d912..99a6ae8424 100644
--- a/apps/cua-spaces-web/src/bridge/adapters/demo/driver.ts
+++ b/apps/cua-spaces-web/src/bridge/adapters/demo/driver.ts
@@ -72,7 +72,7 @@ function setPath(config: DriverConfig, key: string, value: unknown): void {
}
export function demoDriverHandlers({ state, now, wait, emit, stepMs }: DemoContext): DemoHandlers<
- "driver.status" | "driver.list" | "driver.config" | "driver.setConfig" | "driver.test" | "driver.pause" | "driver.setApp" | "driver.setup" | "driver.update"
+ "driver.status" | "driver.list" | "driver.config" | "driver.setConfig" | "driver.test" | "driver.pause" | "driver.setApp" | "driver.setup" | "driver.update" | "driver.permissions"
> {
const d = () => state.driver;
const permissions = (): DriverPermission[] =>
@@ -94,6 +94,7 @@ export function demoDriverHandlers({ state, now, wait, emit, stepMs }: DemoConte
lastTest: d().lastTest ? { ...d().lastTest! } : null,
lastError: null,
permissions: perms,
+ appName: "Cua Spaces",
apps: d().apps.map((a) => ({ ...a })),
activity: allowed && !d().paused && d().lastTest ? [{ app: "Claude Code", target: "Xcode" }] : [],
canPause: true,
@@ -136,6 +137,7 @@ export function demoDriverHandlers({ state, now, wait, emit, stepMs }: DemoConte
const s = status();
return [{ machineId: "this-mac", name: "This Mac", os: "macos", thisMachine: true, state: s.state, version: s.version, update: s.update?.version ?? null }, ...d().others.map((m) => ({ ...m }))];
},
+ "driver.permissions": () => ({ appName: "Cua Spaces", permissions: permissions() }),
"driver.config": () => structuredClone(d().config),
"driver.setConfig": ({ changes }) => {
for (const [k, v] of Object.entries(changes)) setPath(d().config, k, v);
diff --git a/apps/cua-spaces-web/src/bridge/app-permissions.ts b/apps/cua-spaces-web/src/bridge/app-permissions.ts
new file mode 100644
index 0000000000..264f947786
--- /dev/null
+++ b/apps/cua-spaces-web/src/bridge/app-permissions.ts
@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+/**
+ * Cua Spaces' own Screen Recording and Accessibility (`driver.permissions`,
+ * `ops/driver.ts`), the grants Cua Driver uses. One read for every place that
+ * shows them: the first run's permissions step, its next steps, the Cua
+ * Driver page and This Mac. Each reads while it shows: at once, every few
+ * seconds and when the app comes back to the front (System Settings is
+ * where the person turns them on), so a grant shows without a click.
+ *
+ * Allow is `host.openSettings` with the row's pane, which the Mac app turns
+ * into its permission guide (PermissionGuide). The host restarts a driver
+ * that still says no once both are on.
+ *
+ * A host with no permissions to give (Windows, Linux, an older app) answers
+ * null or refuses: `available` is false and nothing is drawn.
+ */
+
+import { useCallback, useContext, useEffect, useRef, useState } from "react";
+
+import { BridgeContext } from "./BridgeProvider";
+import type { AppPermissions, DriverPermission } from "./ops/driver";
+
+export type { AppPermissions } from "./ops/driver";
+
+export const APP_PERMISSIONS_POLL_MS = 2_500;
+
+export interface AppPermissionsState {
+ /** Null until the first answer, and on a host with none to give. */
+ data: AppPermissions | null;
+ /** The first read hasn't answered. */
+ loading: boolean;
+ /** The host has the two permissions (a Mac). False while loading. */
+ available: boolean;
+ /** Both are on. */
+ allGranted: boolean;
+ /** Opens the app's guide to the row's pane in System Settings. */
+ allow: (id: DriverPermission["id"]) => Promise<void>;
+ /** Reads them again now. */
+ refresh: () => Promise<void>;
+}
+
+/** Reads while `active` (default on). */
+export function useAppPermissions(active = true): AppPermissionsState {
+ const adapter = useContext(BridgeContext)?.adapter ?? null;
+ const [data, setData] = useState<AppPermissions | null>(null);
+ const [loading, setLoading] = useState(true);
+ const reading = useRef(false);
+ const live = useRef(true);
+
+ const refresh = useCallback(async () => {
+ if (!adapter) return setLoading(false);
+ if (reading.current) return;
+ reading.current = true;
+ try {
+ const next = await adapter.call("driver.permissions", {}).catch(() => null);
+ if (live.current) setData(next);
+ } finally {
+ reading.current = false;
+ if (live.current) setLoading(false);
+ }
+ }, [adapter]);
+
+ useEffect(() => {
+ live.current = true;
+ if (!active) return;
+ void refresh();
+ const t = setInterval(() => void refresh(), APP_PERMISSIONS_POLL_MS);
+ const again = () => {
+ if (document.visibilityState !== "hidden") void refresh();
+ };
+ window.addEventListener("focus", again);
+ document.addEventListener("visibilitychange", again);
+ return () => {
+ live.current = false;
+ clearInterval(t);
+ window.removeEventListener("focus", again);
+ document.removeEventListener("visibilitychange", again);
+ };
+ }, [active, refresh]);
+
+ const allow = useCallback(
+ async (id: DriverPermission["id"]) => {
+ const url = data?.permissions.find((p) => p.id === id)?.settingsUrl;
+ if (!adapter || !url) return;
+ await adapter.call("host.openSettings", { url });
+ void refresh();
+ },
+ [adapter, data, refresh],
+ );
+
+ const permissions = data?.permissions ?? [];
+ return {
+ data,
+ loading,
+ available: permissions.length > 0,
+ allGranted: permissions.length > 0 && permissions.every((p) => p.granted),
+ allow,
+ refresh,
+ };
+}
diff --git a/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.json b/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.json
index 176850d1a8..e8d77d1dbe 100644
--- a/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.json
+++ b/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.json
@@ -2088,6 +2088,31 @@
"failure"
]
},
+ "DriverPermission": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "enum": [
+ "screen",
+ "accessibility"
+ ]
+ },
+ "granted": {
+ "type": "boolean"
+ },
+ "settingsUrl": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "id",
+ "granted",
+ "settingsUrl"
+ ]
+ },
"DriverStatus": {
"type": "object",
"properties": {
@@ -2156,31 +2181,15 @@
"permissions": {
"type": "array",
"items": {
- "type": "object",
- "properties": {
- "id": {
- "enum": [
- "screen",
- "accessibility"
- ]
- },
- "granted": {
- "type": "boolean"
- },
- "settingsUrl": {
- "type": [
- "string",
- "null"
- ]
- }
- },
- "required": [
- "id",
- "granted",
- "settingsUrl"
- ]
+ "$ref": "#/$defs/DriverPermission"
}
},
+ "appName": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
"apps": {
"type": [
"array",
@@ -9318,6 +9327,27 @@
"driver.pause": {
"type": "null"
},
+ "driver.permissions": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "properties": {
+ "appName": {
+ "type": "string"
+ },
+ "permissions": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/DriverPermission"
+ }
+ }
+ },
+ "required": [
+ "appName",
+ "permissions"
+ ]
+ },
"driver.setApp": {
"type": "null"
},
@@ -12851,6 +12881,27 @@
"driver.pause": {
"type": "null"
},
+ "driver.permissions": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "properties": {
+ "appName": {
+ "type": "string"
+ },
+ "permissions": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/DriverPermission"
+ }
+ }
+ },
+ "required": [
+ "appName",
+ "permissions"
+ ]
+ },
"driver.setApp": {
"type": "null"
},
diff --git a/apps/cua-spaces-web/src/bridge/contracts/shapes.ts b/apps/cua-spaces-web/src/bridge/contracts/shapes.ts
index 427eb3c932..7fee784fce 100644
--- a/apps/cua-spaces-web/src/bridge/contracts/shapes.ts
+++ b/apps/cua-spaces-web/src/bridge/contracts/shapes.ts
@@ -68,7 +68,7 @@ import type { GithubAccount, GithubHost, GithubReport, GithubSourceRow } from ".
import type { TelemetryLinkNotice } from "../ops/telemetry";
import type { SentFileInfo, SpaceThumbnail, SpaceUsage, SpaceWindows } from "../ops/space-detail";
import type { RelayUsage } from "../ops/relay-usage";
-import type { DriverActivity, DriverApp, DriverLiveTest, DriverMachine, DriverPermission, DriverStatus, DriverUpdate } from "../ops/driver";
+import type { AppPermissions, DriverActivity, DriverApp, DriverLiveTest, DriverMachine, DriverPermission, DriverStatus, DriverUpdate } from "../ops/driver";
import type { DefaultSpace, DefaultSpaceStep, SpacesSettings } from "../ops/spaces-settings";
import type { RiskyRequest } from "../ops/nudges";
import type { PastMessage, PastThread, RecentThread } from "../ops/agent-threads";
@@ -107,6 +107,7 @@ const RecentThreadShape = ref(
obj<RecentThread>()({ agent: oneOf("claude-code", "openai-codex", "hermes"), id: str, title: str, cwd: nullable(str), lastActiveMs: num, resume: strings }),
);
const DriverLiveTestShape = ref("DriverLiveTest", obj<DriverLiveTest>()({ passed: bool, atMs: num, failure: nullable(str), tookMs: optNull(num) }));
+const DriverPermissionShape = ref("DriverPermission", obj<DriverPermission>()({ id: oneOf("screen", "accessibility"), granted: bool, settingsUrl: nullable(str) }));
const DriverStatusShape = ref(
"DriverStatus",
obj<DriverStatus>()({
@@ -118,7 +119,8 @@ const DriverStatusShape = ref(
update: nullable(obj<DriverUpdate>()({ version: str, note: nullable(str) })),
lastTest: nullable(DriverLiveTestShape),
lastError: nullable(str),
- permissions: list(obj<DriverPermission>()({ id: oneOf("screen", "accessibility"), granted: bool, settingsUrl: nullable(str) })),
+ permissions: list(DriverPermissionShape),
+ appName: optNull(str),
apps: nullable(list(obj<DriverApp>()({ id: str, name: str, on: bool, own: bool, bringsOwn: bool }))),
activity: list(obj<DriverActivity>()({ app: str, target: str })),
canPause: bool,
@@ -1635,6 +1637,7 @@ export const OP_SHAPES: Record<OpName, Schema> = {
"driver.pause": nul,
"driver.setApp": nul,
"driver.update": nul,
+ "driver.permissions": nullable(obj<AppPermissions>()({ appName: str, permissions: list(DriverPermissionShape) })),
"relay.usage": nullable(
obj<RelayUsage>()({
metered: bool,
@@ -2107,6 +2110,7 @@ export const WEBKIT_SHAPES: Partial<Record<WebkitMethod, Schema>> = {
"driver.pause": OP_SHAPES["driver.pause"],
"driver.setup": OP_SHAPES["driver.setup"],
"driver.setApp": OP_SHAPES["driver.setApp"],
+ "driver.permissions": OP_SHAPES["driver.permissions"],
"agents.detail": AgentDetailShape,
"agents.readFile": AgentOpenFileShape,
"agents.restoreFile": nul,
diff --git a/apps/cua-spaces-web/src/bridge/ops/driver.ts b/apps/cua-spaces-web/src/bridge/ops/driver.ts
index 1bfee0222b..bf5a8dc211 100644
--- a/apps/cua-spaces-web/src/bridge/ops/driver.ts
+++ b/apps/cua-spaces-web/src/bridge/ops/driver.ts
@@ -13,6 +13,7 @@
* | `driver.config`, `driver.setConfig` | `get_config` / `set_config` on the driver | unsupported |
* | `driver.test`, `driver.pause`, `driver.setup`, `driver.setApp` | the host methods of the same names | unsupported |
* | `driver.update` | fails by design: the driver updates with Cua Spaces | unsupported |
+ * | `driver.permissions` | the host method of the same name | unsupported |
*
* The Electron shell (Windows, Linux) runs the driver in-process in
* `cua-spacesd` and routes none of these methods: its "unimplemented"
@@ -29,6 +30,12 @@
* Codex's MCP configs, starts a driver whose permission answer is stale
* again, runs the live test, and answers the new status.
*
+ * `driver.permissions` is Cua Spaces' own Screen Recording and Accessibility,
+ * which the driver uses: answered on any Mac, with or without a driver (the
+ * first run's permissions step, the Driver page, This Mac). Once both are
+ * on, the host starts a driver whose answer is stale again, once. The
+ * Electron shell answers null: no step, no rows.
+ *
* Settings are the driver's own `get_config` JSON as-is (`driver.config`);
* `driver.setConfig` takes `set_config` keys (`cursor.float`,
* `cursor.marks`, `cursor.rotate`, `cursor.motion.style`, `cursor.badges`).
@@ -49,6 +56,13 @@ export interface DriverPermission {
settingsUrl: string | null;
}
+/** Cua Spaces' own permissions (`driver.permissions`), which Cua Driver uses. */
+export interface AppPermissions {
+ /** The name System Settings lists the app under: "Cua Spaces", or "Cua Spaces Local" (its own grants). */
+ appName: string;
+ permissions: DriverPermission[];
+}
+
/** `embedded_driver::LiveTest`: both permissions, the screen read, and one agent-pointer move. */
export interface DriverLiveTest {
passed: boolean;
@@ -104,6 +118,8 @@ export interface DriverStatus {
lastTest: DriverLiveTest | null;
lastError: string | null;
permissions: DriverPermission[];
+ /** The app the permissions are given to ("Cua Spaces Local"); absent from older hosts. */
+ appName?: string | null;
/** Null: the host can't say which apps use it (the section hides). */
apps: DriverApp[] | null;
activity: DriverActivity[];
@@ -142,6 +158,8 @@ export interface DriverOps {
/** Set up and Repair: the agents' MCP entries, a fresh driver, the live test. */
"driver.setup": { args: Record<string, never>; result: DriverStatus | null };
"driver.update": { args: Machine; result: null };
+ /** Cua Spaces' own Screen Recording and Accessibility; null where the app has none to give (Windows, Linux). */
+ "driver.permissions": { args: Record<string, never>; result: AppPermissions | null };
}
export const DRIVER_OPERATIONS = [
@@ -154,6 +172,7 @@ export const DRIVER_OPERATIONS = [
"driver.setApp",
"driver.setup",
"driver.update",
+ "driver.permissions",
] as const satisfies readonly (keyof DriverOps)[];
const TAURI = "the Tauri shell is not the shipped app and runs no embedded driver";
@@ -179,6 +198,7 @@ export function webkitDriverOps(request: <T>(method: WebkitMethod, args?: Record
"driver.setApp": (a) => request<null>("driver.setApp", { app: a.app, on: a.on }),
"driver.setup": () => request<DriverStatus | null>("driver.setup"),
"driver.update": () => Promise.reject(new HostError(UPDATE, "by_design")),
+ "driver.permissions": () => request<AppPermissions | null>("driver.permissions"),
};
}
@@ -193,4 +213,5 @@ export const DRIVER_ARGS = {
"driver.setApp": { app: "codex", on: true },
"driver.setup": {},
"driver.update": {},
+ "driver.permissions": {},
};
diff --git a/apps/cua-spaces-web/src/bridge/webkit-protocol.ts b/apps/cua-spaces-web/src/bridge/webkit-protocol.ts
index ccb86d81e5..dc4ca6f22a 100644
--- a/apps/cua-spaces-web/src/bridge/webkit-protocol.ts
+++ b/apps/cua-spaces-web/src/bridge/webkit-protocol.ts
@@ -208,6 +208,7 @@ export const WEBKIT_METHODS = [
"driver.pause",
"driver.setup",
"driver.setApp",
+ "driver.permissions",
"resources.get",
"machines.rename",
"machines.remove",
diff --git a/apps/cua-spaces-web/src/components/__tests__/driver.test.tsx b/apps/cua-spaces-web/src/components/__tests__/driver.test.tsx
index eca969fbfd..79977ee83a 100644
--- a/apps/cua-spaces-web/src/components/__tests__/driver.test.tsx
+++ b/apps/cua-spaces-web/src/components/__tests__/driver.test.tsx
@@ -89,7 +89,7 @@ describe("Cua Driver in the app", () => {
expect(document.querySelector("[data-driver-app=claude-code]")?.textContent).toContain("Uses Cua Driver in Cua Spaces.");
expect(document.querySelector("[data-driver-app=codex]")?.textContent).toContain("Not connected. Set up connects it.");
expect(document.querySelector("[data-driver-app=t3-code]")?.textContent).toContain("Brings its own Cua Driver");
- expect(document.querySelector("[data-driver-permission=screen]")?.textContent).toContain("On");
+ await waitFor(() => expect(document.querySelector("[data-app-permission=screen]")?.textContent).toContain("On"));
expect(document.querySelector("[data-driver-computers]")).toBeNull();
});
@@ -146,8 +146,13 @@ describe("Cua Driver in the app", () => {
});
mount(spy, () => <DriverPage machine={null} />);
expect(await screen.findByText("A permission is missing. Allow it below.")).toBeTruthy();
- expect(document.querySelector("[data-driver-permission=screen]")?.textContent).toContain("Missing");
+ await waitFor(() => expect(document.querySelector("[data-app-permission=screen]")?.textContent).toContain("Missing"));
+ // The app the grant goes to, by name, and that the driver needs no second one.
+ expect(document.querySelector("[data-app-permission=screen]")?.textContent).toContain("Screen Recording, given to Cua Spaces");
+ expect(document.body.textContent).toContain("Cua Driver uses the permissions you give Cua Spaces. It never asks for its own.");
fireEvent.click(screen.getByRole("button", { name: "Allow" }));
await waitFor(() => expect(calls).toContain("host.openSettings"));
+ // The demo plays the grant in System Settings: the row turns On without another click.
+ await waitFor(() => expect(document.querySelector("[data-app-permission=screen]")?.textContent).toContain("On"), { timeout: 5_000 });
});
});
diff --git a/apps/cua-spaces-web/src/components/app-permissions.tsx b/apps/cua-spaces-web/src/components/app-permissions.tsx
new file mode 100644
index 0000000000..f32121d588
--- /dev/null
+++ b/apps/cua-spaces-web/src/components/app-permissions.tsx
@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+/**
+ * Cua Spaces' two permissions, Screen Recording and Accessibility, with
+ * Allow and their live status (`useAppPermissions`). One component for every
+ * place that shows them: the first run's permissions step and next steps
+ * (`hero`, drawn on the spaces.cua.ai hero) and the Cua Driver page and
+ * This Mac (`settings`, the app's grouped rows). Cua Driver uses these same
+ * grants, so there is no second app to allow.
+ */
+
+import { CheckIcon } from "lucide-react";
+import type { ReactNode } from "react";
+
+import type { AppPermissionsState } from "@/bridge/app-permissions";
+import { CARD, GLASS_CHIP, GREY } from "@/components/first-run-new/hero";
+import { Button } from "@/components/ui/button";
+import { GroupedSection, SettingRow } from "@/components/ui/grouped";
+import { toastError } from "@/components/ui/toast";
+import { allowHint, permissionWords } from "@/lib/app-permissions";
+import { cn } from "@/lib/utils";
+
+export function AppPermissionList({
+ perms,
+ variant,
+ title = "Permissions",
+ footer,
+ inset,
+ className,
+}: {
+ perms: Pick<AppPermissionsState, "data" | "allow">;
+ variant: "hero" | "settings";
+ /** The settings section's heading. */
+ title?: string;
+ /** Under the rows; the hero's default says what Allow does. */
+ footer?: ReactNode;
+ /** Hero rows inside another card (the next steps' row): no card of their own. */
+ inset?: boolean;
+ className?: string;
+}) {
+ const data = perms.data;
+ if (!data?.permissions.length) return null;
+ const allow = (id: Parameters<typeof perms.allow>[0]) => void perms.allow(id).catch(toastError("Couldn't open System Settings"));
+
+ if (variant === "settings") {
+ return (
+ <GroupedSection title={title} className={cn("mb-8", className)} data-app-permissions="" footer={footer}>
+ {data.permissions.map((p) => {
+ const words = permissionWords(p.id, data.appName);
+ return (
+ <SettingRow
+ key={p.id}
+ data-app-permission={p.id}
+ data-granted={p.granted ? "" : undefined}
+ label={words.title}
+ help={`${words.sub}.`}
+ value={p.granted ? "On" : "Missing"}
+ control={
+ p.granted || !p.settingsUrl ? undefined : (
+ <Button variant="outline" size="sm" onClick={() => allow(p.id)}>
+ Allow
+ </Button>
+ )
+ }
+ />
+ );
+ })}
+ </GroupedSection>
+ );
+ }
+
+ return (
+ <div className={className} data-app-permissions="">
+ <div className={inset ? undefined : CARD}>
+ {data.permissions.map((p) => {
+ const words = permissionWords(p.id, data.appName);
+ return (
+ <div key={p.id} className="flex min-h-[52px] items-center gap-3 px-3 py-[7px]" data-app-permission={p.id} data-granted={p.granted ? "" : undefined}>
+ <span className="min-w-0 flex-1">
+ <span className="block text-[15px] leading-5 font-medium text-white">{words.title}</span>
+ <span className={cn("block text-[13.5px] leading-[19px] font-medium", GREY)}>{words.sub}</span>
+ </span>
+ {p.granted ? (
+ <span className="flex items-center gap-1 pr-1 text-[13.5px] font-medium text-white" role="status">
+ <CheckIcon aria-hidden className="size-3.5" strokeWidth={2.6} /> Allowed
+ </span>
+ ) : p.settingsUrl ? (
+ <button type="button" className={cn(GLASS_CHIP, "h-[30px] shrink-0 px-3.5 text-[13.5px]")} onClick={() => allow(p.id)}>
+ Allow
+ </button>
+ ) : null}
+ </div>
+ );
+ })}
+ </div>
+ <p className={cn(inset ? "mt-1 px-3 pb-1" : "mt-3 px-1", "max-w-[480px] text-[13.5px] leading-[19px] font-medium", GREY)}>{footer ?? allowHint(data.appName)}</p>
+ </div>
+ );
+}
diff --git a/apps/cua-spaces-web/src/components/driver/driver-page.tsx b/apps/cua-spaces-web/src/components/driver/driver-page.tsx
index d18696a51c..5151675c5e 100644
--- a/apps/cua-spaces-web/src/components/driver/driver-page.tsx
+++ b/apps/cua-spaces-web/src/components/driver/driver-page.tsx
@@ -3,10 +3,12 @@
import { Link } from "@tanstack/react-router";
import { CheckIcon, ChevronRightIcon, MousePointer2Icon } from "lucide-react";
-import { useState } from "react";
+import { useEffect, useRef, useState } from "react";
-import { pointerChange, pointerSettings, POINTER_STYLES, useBridge, useDriver, useDriverMachines, type DriverApp, type DriverHook, type DriverPermission, type DriverStatus, type PointerSettings } from "@/bridge";
+import { pointerChange, pointerSettings, POINTER_STYLES, useDriver, useDriverMachines, type DriverApp, type DriverHook, type DriverStatus, type PointerSettings } from "@/bridge";
+import { useAppPermissions } from "@/bridge/app-permissions";
import { AppMarkImage } from "@/components/agents/harness-mark";
+import { AppPermissionList } from "@/components/app-permissions";
import { CuaKey } from "@/components/cua-key";
import { OsIcon } from "@/components/os-icon";
import { EmptyState, Page } from "@/components/page";
@@ -16,6 +18,7 @@ import { Segmented } from "@/components/ui/segmented";
import { Select } from "@/components/ui/select";
import { Switch } from "@/components/ui/switch";
import { toast, toastError } from "@/components/ui/toast";
+import { driverUsesAppPermissions } from "@/lib/app-permissions";
import { cn } from "@/lib/utils";
import { DRIVER_LINE, markFor, stateText, testText, versionText } from "./copy";
import { PointerPreview } from "./pointer-preview";
@@ -55,7 +58,7 @@ function DriverBody({ driver, status }: { driver: DriverHook; status: DriverStat
{hasPointer ? <PointerSection driver={driver} settings={settings} /> : null}
<div className="min-w-0">
{apps ? <AppsSection apps={apps} /> : null}
- {status.permissions.length > 0 ? <PermissionsSection permissions={status.permissions} /> : null}
+ {status.thisMachine ? <PermissionsSection driver={driver} /> : null}
{!status.thisMachine ? (
<GroupedSection title="On that computer" className="mb-8">
<SettingRow label="Pointer and coding apps" help={`Open Cua Spaces on ${status.machineName} to change them.`} />
@@ -255,34 +258,17 @@ function AppsSection({ apps }: { apps: DriverApp[] }) {
);
}
-const PERMISSION_WORDS: Record<DriverPermission["id"], { label: string; help: string }> = {
- screen: { label: "See the screen", help: "Screen Recording, given to Cua Spaces." },
- accessibility: { label: "Use the mouse and keyboard", help: "Accessibility, given to Cua Spaces." },
-};
-
-function PermissionsSection({ permissions }: { permissions: DriverPermission[] }) {
- const { data: adapter } = useBridge();
- return (
- <GroupedSection title="Permissions" className="mb-8" data-driver-permissions="" footer="Cua Driver uses the permissions you give Cua Spaces. It never asks for its own.">
- {permissions.map((p) => (
- <SettingRow
- key={p.id}
- data-driver-permission={p.id}
- data-driver-permission-granted={p.granted ? "" : undefined}
- label={PERMISSION_WORDS[p.id].label}
- help={PERMISSION_WORDS[p.id].help}
- value={p.granted ? "On" : "Missing"}
- control={
- p.granted || !p.settingsUrl ? undefined : (
- <Button variant="outline" size="sm" onClick={() => void adapter?.call("host.openSettings", { url: p.settingsUrl! }).catch(toastError("Couldn't open System Settings"))}>
- Allow
- </Button>
- )
- }
- />
- ))}
- </GroupedSection>
- );
+/** Cua Spaces' own two permissions, live (the first run's step shows the same rows); when both come on, the driver's state is read again. */
+function PermissionsSection({ driver }: { driver: DriverHook }) {
+ const perms = useAppPermissions();
+ const { allGranted } = perms;
+ const refresh = useRef(driver.refresh);
+ refresh.current = driver.refresh;
+ useEffect(() => {
+ if (allGranted) void refresh.current().catch(() => {});
+ }, [allGranted]);
+ if (!perms.data) return null;
+ return <AppPermissionList perms={perms} variant="settings" footer={driverUsesAppPermissions(perms.data.appName)} />;
}
/* ---- The account's other computers -------------------------------------------- */
diff --git a/apps/cua-spaces-web/src/components/first-run-new/first-run-new.tsx b/apps/cua-spaces-web/src/components/first-run-new/first-run-new.tsx
index 0be148ad4d..79743ddea5 100644
--- a/apps/cua-spaces-web/src/components/first-run-new/first-run-new.tsx
+++ b/apps/cua-spaces-web/src/components/first-run-new/first-run-new.tsx
@@ -15,18 +15,21 @@ import { useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, type
import { folderLabel, newPendingId, useMachines, useSession, useSettings, useSpaces, type SignInPhase } from "@/bridge";
import { BridgeContext } from "@/bridge/BridgeProvider";
-import type { HostStatus } from "@/bridge/contracts/host";
+import { useAppPermissions, type AppPermissionsState } from "@/bridge/app-permissions";
import { readFirstRun, useFirstRunSaved, writeFirstRun } from "@/bridge/first-run";
import { hostOs } from "@/bridge/host-os";
import { useFirstSpaceOffers } from "@/bridge/new-space-hooks";
import { readSavedOnboarding, writeSavedOnboarding } from "@/bridge/onboarding";
import { extraName, spokenName } from "@/bridge/space-names";
import { AddComputerSheet } from "@/components/add-computer-sheet";
+import { AppPermissionList } from "@/components/app-permissions";
import { AppMarkImage } from "@/components/agents/harness-mark";
import { agoLabel, useRecentThreads } from "@/components/ask-first/pick-up";
import { CuaLogo } from "@/components/cua-logo";
+import { permissionsStepView, type PermissionsStepView } from "@/lib/app-permissions";
import { addImportedTask, type AskTask } from "@/lib/ask-first";
import {
+ afterWhere,
agentView,
chosenAgent,
dotStep,
@@ -54,12 +57,11 @@ import { spaceState } from "@/lib/spaces";
import { cn } from "@/lib/utils";
import { FloatKeys } from "./float-keys";
+import { CARD, GLASS_CHIP, GREY } from "./hero";
import { OsMark } from "./os-marks";
/* ---- The site's pieces ------------------------------------------------------------------ */
-/** The hero's grey for second lines. */
-const GREY = "text-[#8d8d8d]";
/** The site's white button (the dark hero's Download pill). */
const WHITE_BUTTON =
// design-ok: the first run is drawn from the spaces.cua.ai hero (storyboard CUA-3193), not the app's pages
@@ -68,15 +70,9 @@ const WHITE_BUTTON =
const GLASS_BUTTON =
// design-ok: the first run is drawn from the spaces.cua.ai hero (storyboard CUA-3193), not the app's pages
"inline-flex h-12 items-center justify-center rounded-full bg-white/[0.08] px-6 text-[15px] font-semibold text-white shadow-[inset_0_0_0_1px_rgb(255_255_255/0.28)] backdrop-blur-md outline-none hover:bg-white/[0.14] focus-visible:ring-2 focus-visible:ring-[#5ec0e8]";
-/** The site's Sign up chip (Skip for now, a row's Add). */
-const GLASS_CHIP =
- "inline-flex items-center justify-center rounded-full bg-white/[0.08] font-semibold text-white shadow-[inset_0_0_0_1px_rgb(255_255_255/0.28)] backdrop-blur-md outline-none hover:bg-white/[0.14] focus-visible:ring-2 focus-visible:ring-[#5ec0e8]";
/** The site's underlined text link, in white. */
// design-ok: the first run is drawn from the spaces.cua.ai hero (storyboard CUA-3193), not the app's pages
const LINK = "font-semibold text-white underline decoration-white/50 underline-offset-[3px] outline-none hover:decoration-white focus-visible:ring-2 focus-visible:ring-[#5ec0e8] rounded-sm";
-/** The list card: the Sign up glass with the download menu's corners. */
-// design-ok: the first run is drawn from the spaces.cua.ai hero (storyboard CUA-3193), not the app's pages
-const CARD = "w-full max-w-[480px] rounded-[20px] bg-white/[0.08] p-1.5 shadow-[inset_0_0_0_1px_rgb(255_255_255/0.28)] backdrop-blur-md";
function Title({ children }: { children: ReactNode }) {
return (
@@ -615,27 +611,18 @@ export function NextScreen({ view, onRow, onDone, apps }: { view: NextView; onRo
);
}
-/** "Let agents use apps on this Mac", opened: the two permissions, each through the app's guide (PermissionGuide). */
-export function AppsPermissions({ rows, onAllow }: { rows: { id: string; title: string; granted: boolean; url: string }[]; onAllow: (url: string) => void }) {
- // design-ok: the first run is drawn from the spaces.cua.ai hero (storyboard CUA-3193), not the app's pages
- const box = "mx-3 mb-2 flex flex-col gap-1 border-t border-white/[0.14] pt-2 pl-10";
+/** 2b, on a Mac: Cua Spaces' two permissions (the same rows as the Cua Driver page), each with Allow, and Later. Never blocks the run. */
+export function PermissionsScreen({ view, perms, onContinue }: { view: PermissionsStepView; perms: Pick<AppPermissionsState, "data" | "allow">; onContinue: () => void }) {
return (
- <div className={box} data-new-run-apps="">
- {rows.map((r) => (
- <div key={r.id} className="flex min-h-9 items-center gap-3" data-new-run-permission={r.id} data-granted={String(r.granted)}>
- <span className="min-w-0 flex-1 text-[14px] font-medium text-white">{r.title}</span>
- {r.granted ? (
- <span className="flex items-center gap-1 text-[13.5px] font-medium text-white">
- <CheckIcon className="size-3.5" /> Allowed
- </span>
- ) : (
- <button type="button" className={cn(GLASS_CHIP, "h-[30px] px-3.5 text-[13.5px]")} onClick={() => onAllow(r.url)}>
- Allow
- </button>
- )}
- </div>
- ))}
- <p className={cn("pb-1 text-[12.5px] font-medium", GREY)}>Allow opens System Settings, where you turn on Cua Spaces.</p>
+ <div data-new-run="permissions">
+ <Title>{view.title}</Title>
+ <Line>{view.line}</Line>
+ <AppPermissionList perms={perms} variant="hero" className="mt-[min(28px,3vh)]" footer={view.note} />
+ <Actions>
+ <button type="button" className={view.primary.white ? WHITE_BUTTON : GLASS_BUTTON} onClick={onContinue} data-onboarding-primary="" data-new-run-permissions-next={view.primary.label}>
+ {view.primary.label}
+ </button>
+ </Actions>
</div>
);
}
@@ -645,11 +632,6 @@ export function AppsPermissions({ rows, onAllow }: { rows: { id: string; title:
/** The daemon's refusal on a Mac that can't run virtual computers (`cua_create_failure::preflight::MAC_UNSUPPORTED`). */
const CANT_RUN = /can['\u2019]t run (Spaces itself|virtual computers)/i;
-const PERMISSIONS = [
- { id: "screen-recording", title: "See the screen", url: "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture" },
- { id: "accessibility", title: "Use the mouse and keyboard", url: "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility" },
-];
-
/** The new first run's whole page. */
export function NewFirstRun() {
const navigate = useNavigate();
@@ -685,7 +667,6 @@ export function NewFirstRun() {
const [appsOpen, setAppsOpen] = useState(false);
const mainRef = useRef<HTMLElement>(null);
useFadeUnder(mainRef, s.screen);
- const [host, setHost] = useState<HostStatus | null>(null);
// A new screen: focus moves to its title, so a screen reader reads it. Moved with the arrow keys on the
// step dots, focus stays on the dots instead.
@@ -781,24 +762,13 @@ export function NewFirstRun() {
};
}, [s.screen, adapter]);
- // Screen 6's permissions, read while they show.
+ // 2b and screen 6's apps row: Cua Spaces' permissions, read while they show. A host with none to give (not a
+ // Mac, an older app) has no step: it goes on to the coding agent.
+ const perms = useAppPermissions(s.screen === "permissions" || (s.screen === "next" && appsOpen));
useEffect(() => {
- if (!appsOpen || !adapter) return;
- let live = true;
- const read = () =>
- void adapter
- .call("host.status", {})
- .then((h) => live && setHost(h))
- .catch(() => {});
- read();
- const t = setInterval(read, 2_500);
- window.addEventListener("focus", read);
- return () => {
- live = false;
- clearInterval(t);
- window.removeEventListener("focus", read);
- };
- }, [appsOpen, adapter]);
+ if (s.screen === "permissions" && !perms.loading && !perms.available) go("agent");
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [s.screen, perms.loading, perms.available]);
// The separate computer: this page's create, followed in the Spaces list.
const linux = offers.offers.find((o) => o.id === "linux") ?? null;
@@ -961,10 +931,13 @@ export function NewFirstRun() {
onSignIn={startSignIn}
onAddAnother={() => setAddOpen(true)}
onSeparate={makeSeparate}
- onContinue={() => go("agent")}
+ onContinue={() => go(afterWhere(os))}
/>
);
break;
+ case "permissions":
+ body = <PermissionsScreen view={permissionsStepView({ appName: perms.data?.appName ?? "Cua Spaces", allGranted: perms.allGranted })} perms={perms} onContinue={() => go("agent")} />;
+ break;
case "agent":
body = (
<AgentScreen
@@ -985,7 +958,6 @@ export function NewFirstRun() {
) : null;
break;
case "next": {
- const granted = (id: string) => Boolean(host?.permissions.find((p) => p.id === id)?.granted);
body = (
<NextScreen
view={nextView({ os })}
@@ -996,12 +968,8 @@ export function NewFirstRun() {
}}
onDone={() => void finish()}
apps={
- appsOpen ? (
- <AppsPermissions
- rows={PERMISSIONS.map((p) => ({ ...p, granted: granted(p.id), url: host?.permissions.find((x) => x.id === p.id)?.settingsUrl ?? p.url }))}
- onAllow={(url) => void adapter?.call("host.openSettings", { url }).catch(() => {})}
- />
- ) : null
+ // design-ok: the first run is drawn from the spaces.cua.ai hero (storyboard CUA-3193), not the app's pages
+ appsOpen ? <AppPermissionList perms={perms} variant="hero" inset className="mx-3 mb-2 border-t border-white/[0.14] pt-2 pl-7" /> : null
}
/>
);
diff --git a/apps/cua-spaces-web/src/components/first-run-new/hero.ts b/apps/cua-spaces-web/src/components/first-run-new/hero.ts
new file mode 100644
index 0000000000..337a0ab158
--- /dev/null
+++ b/apps/cua-spaces-web/src/components/first-run-new/hero.ts
@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+/** The spaces.cua.ai hero's pieces the first run draws with (storyboard CUA-3193), shared with the pieces it borrows. */
+
+/** The hero's grey for second lines. */
+export const GREY = "text-[#8d8d8d]";
+/** The site's Sign up chip (Skip for now, a row's Add). */
+export const GLASS_CHIP =
+ "inline-flex items-center justify-center rounded-full bg-white/[0.08] font-semibold text-white shadow-[inset_0_0_0_1px_rgb(255_255_255/0.28)] backdrop-blur-md outline-none hover:bg-white/[0.14] focus-visible:ring-2 focus-visible:ring-[#5ec0e8]";
+/** The list card: the Sign up glass with the download menu's corners. */
+// design-ok: the first run is drawn from the spaces.cua.ai hero (storyboard CUA-3193), not the app's pages
+export const CARD = "w-full max-w-[480px] rounded-[20px] bg-white/[0.08] p-1.5 shadow-[inset_0_0_0_1px_rgb(255_255_255/0.28)] backdrop-blur-md";
diff --git a/apps/cua-spaces-web/src/components/this-machine.tsx b/apps/cua-spaces-web/src/components/this-machine.tsx
index 07c050d02f..a26389eee4 100644
--- a/apps/cua-spaces-web/src/components/this-machine.tsx
+++ b/apps/cua-spaces-web/src/components/this-machine.tsx
@@ -13,7 +13,9 @@ import {
type HostPanelView,
type HostSetupFormView,
} from "@/bridge";
+import { useAppPermissions } from "@/bridge/app-permissions";
import { throttleSeconds } from "@/bridge/friendly-errors";
+import { AppPermissionList } from "@/components/app-permissions";
import { Button } from "@/components/ui/button";
import { Checkbox } from "@/components/ui/checkbox";
import { GroupedSection, SectionHeading } from "@/components/ui/grouped";
@@ -24,6 +26,9 @@ import { toast } from "@/components/ui/toast";
import { Tooltip } from "@/components/ui/tooltip";
import { cn, relativeTime } from "@/lib/utils";
+/** The permissions `AppPermissionList` draws; any other (Local Network) keeps its own row. */
+const GUIDED = new Set(["screen-recording", "accessibility"]);
+
/** The log open in full ("Show All…"). */
type HostLog = "access" | "activity";
@@ -38,6 +43,8 @@ type HostLog = "access" | "activity";
export function ThisMachineExtras({ panel, progress, part }: { panel: HostPanelView | null; progress?: string; part?: "alerts" | "logs" }) {
const { data: session } = useSession();
const host = useThisMachine(session?.identity ?? null);
+ // Screen Recording and Accessibility: Cua Spaces' own, the same rows and live status as the first run and the Cua Driver page.
+ const perms = useAppPermissions(part === "alerts" && Boolean(panel?.permissionsTitle));
const [fullLog, setFullLog] = useState<HostLog | null>(null);
const now = Date.now();
@@ -62,9 +69,10 @@ export function ThisMachineExtras({ panel, progress, part }: { panel: HostPanelV
</div>
</GroupedSection>
) : null}
- {panel.permissionsTitle ? (
- <Group title={panel.permissionsTitle}>
- {panel.permissions.map((p) => (
+ {panel.permissionsTitle && perms.available ? <AppPermissionList perms={perms} variant="settings" title={panel.permissionsTitle} className="mb-6" /> : null}
+ {panel.permissionsTitle && (!perms.available || panel.permissions.some((p) => !GUIDED.has(p.id))) ? (
+ <Group title={perms.available ? "Also in System Settings" : panel.permissionsTitle}>
+ {panel.permissions.filter((p) => !perms.available || !GUIDED.has(p.id)).map((p) => (
<Row key={p.id} label={p.title} hint={p.help} data-host-permission={p.id}>
{p.settingsUrl ? (
<Button size="sm" variant="secondary" onClick={() => void openSettings(p.settingsUrl!)}>
diff --git a/apps/cua-spaces-web/src/lib/app-permissions.ts b/apps/cua-spaces-web/src/lib/app-permissions.ts
new file mode 100644
index 0000000000..b99679b2e3
--- /dev/null
+++ b/apps/cua-spaces-web/src/lib/app-permissions.ts
@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+/**
+ * The words for Cua Spaces' two permissions, the same wherever they show
+ * (the first run's step, its next steps, the Cua Driver page, This Mac).
+ * Each names the app System Settings lists ("Cua Spaces Local" for the
+ * Local build, which has its own grants), so nobody turns on the wrong one.
+ */
+
+import type { DriverPermission } from "@/bridge/ops/driver";
+
+export interface PermissionWords {
+ title: string;
+ sub: string;
+}
+
+export function permissionWords(id: DriverPermission["id"], appName: string): PermissionWords {
+ return id === "screen"
+ ? { title: "See the screen", sub: `Screen Recording, given to ${appName}` }
+ : { title: "Use the mouse and keyboard", sub: `Accessibility, given to ${appName}` };
+}
+
+/** What Allow does, under the rows. */
+export function allowHint(appName: string): string {
+ return `Allow opens System Settings. Turn on ${appName} there, then come back.`;
+}
+
+/** Under the Cua Driver page's rows: one set of permissions, no second app. */
+export function driverUsesAppPermissions(appName: string): string {
+ return `Cua Driver uses the permissions you give ${appName}. It never asks for its own.`;
+}
+
+/** The first run's permissions step. */
+export interface PermissionsStepView {
+ title: string;
+ line: string;
+ /** Under the rows. */
+ note: string;
+ /** The button: Continue once both are on, else Later (the step never blocks the run). */
+ primary: { label: "Continue" | "Later"; white: boolean };
+}
+
+export function permissionsStepView(input: { appName: string; allGranted: boolean }): PermissionsStepView {
+ return {
+ title: `Let ${input.appName} see and use apps`,
+ line: `This lets your agents work in the apps on this Mac, in the background. Cua Driver uses these same permissions, so there's no second app to allow.`,
+ note: input.allGranted ? "Both are on." : `${allowHint(input.appName)} You can also do this later on the Cua Driver page.`,
+ primary: input.allGranted ? { label: "Continue", white: true } : { label: "Later", white: false },
+ };
+}
diff --git a/apps/cua-spaces-web/src/lib/first-run-new.ts b/apps/cua-spaces-web/src/lib/first-run-new.ts
index 1bc0a5f829..2c3642e1b5 100644
--- a/apps/cua-spaces-web/src/lib/first-run-new.ts
+++ b/apps/cua-spaces-web/src/lib/first-run-new.ts
@@ -10,6 +10,8 @@
* 1b Finish signing in in your browser: Try again, Use a code instead; "Sign-in didn't finish".
* 2 Pick where your agents work: this Mac, the account's other computers (offline ones can't be
* picked), Add another computer you own, and a separate computer on this Mac.
+ * 2b On a Mac: let Cua Spaces see and use apps (Screen Recording and Accessibility, which Cua Driver
+ * uses too), each with Allow, or Later. `lib/app-permissions.ts` has its words.
* 3 The coding agent found on this Mac, or Install Claude Code / Install Codex instead.
* 4 Ready: "<agent> can now use <computers>", one line to try in their own terminal.
* 6 Next steps: invite a teammate, add another computer, let agents use apps on this Mac.
@@ -18,9 +20,14 @@
import type { Machine, SignInPhase } from "@/bridge";
import { relativeTime } from "@/lib/utils";
-export type NewRunScreen = "welcome" | "signin" | "where" | "agent" | "ready" | "next";
+export type NewRunScreen = "welcome" | "signin" | "where" | "permissions" | "agent" | "ready" | "next";
-export const NEW_RUN_SCREENS: NewRunScreen[] = ["welcome", "signin", "where", "agent", "ready", "next"];
+export const NEW_RUN_SCREENS: NewRunScreen[] = ["welcome", "signin", "where", "permissions", "agent", "ready", "next"];
+
+/** The screen after 2: the permissions step on a Mac, else the coding agent. */
+export function afterWhere(os: string): NewRunScreen {
+ return os === "macos" ? "permissions" : "agent";
+}
/** What the run keeps between launches (inside the first run's saved record, so Reset & Show clears it). */
export interface NewRunSaved {
@@ -437,7 +444,7 @@ export function nextView(input: { os: string }): NextView {
/** Which progress dot is lit (screens 1 to 3 have dots; 4 and 6 none). */
export function dotFor(screen: NewRunScreen): number | null {
- return screen === "welcome" || screen === "signin" ? 0 : screen === "where" ? 1 : screen === "agent" ? 2 : null;
+ return screen === "welcome" || screen === "signin" ? 0 : screen === "where" || screen === "permissions" ? 1 : screen === "agent" ? 2 : null;
}
/** The screen each step dot opens. */