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(spaces): "Skip for now" sticks across launches, and Local's agent setup names are guarded (CUA-2221) (#5889)

cua-agents[bot]59cf2877722c
diff --git a/apps/cua-spaces-desktop/src/model/agents.ts b/apps/cua-spaces-desktop/src/model/agents.ts
index 65e90ed1ca..3922b66e53 100644
--- a/apps/cua-spaces-desktop/src/model/agents.ts
+++ b/apps/cua-spaces-desktop/src/model/agents.ts
@@ -380,7 +380,12 @@ export interface AgentSetupRunning {
signIn(agent: string): Promise<void>;
}
-/** The SDK's `AgentSetup`, registering the app's own `cua` as the MCP server. */
+/**
+ * The SDK's `AgentSetup`, registering the app's own `cua` as the MCP server.
+ * The server has no name here: the SDK names it for the app's channel (`cua`,
+ * `cua-local` for Cua Spaces Local), so a Local app never writes over the
+ * released app's entry, and it installs the channel's skill copies.
+ */
export class LiveAgentSetup implements AgentSetupRunning {
private readonly server: AgentMcpServer | undefined;
@@ -389,7 +394,7 @@ export class LiveAgentSetup implements AgentSetupRunning {
private readonly inner: AgentSetupLike,
cuaBinary: string | null,
) {
- this.server = cuaBinary ? { name: "cua", command: cuaBinary, args: ["mcp"], env: new Map() } : undefined;
+ this.server = cuaBinary ? { name: "", command: cuaBinary, args: ["mcp"], env: new Map() } : undefined;
}
private outcomes(list: AgentSetupOutcome[]): AppAgentSetupOutcomeInput[] {
diff --git a/apps/cua-spaces-desktop/test/agents.test.ts b/apps/cua-spaces-desktop/test/agents.test.ts
index a9bf8e50cc..e0c0073a11 100644
--- a/apps/cua-spaces-desktop/test/agents.test.ts
+++ b/apps/cua-spaces-desktop/test/agents.test.ts
@@ -360,7 +360,7 @@ describe.skipIf(!built)("agents", () => {
await live.remove(["codex"]);
expect(seen).toEqual([
["skills", ["codex"], [], false],
- ["mcp", ["codex"], { name: "cua", command: "/Applications/Cua Spaces.app/Contents/MacOS/cua", args: ["mcp"], env: new Map() }],
+ ["mcp", ["codex"], { name: "", command: "/Applications/Cua Spaces.app/Contents/MacOS/cua", args: ["mcp"], env: new Map() }],
["driver", ["codex"], undefined, true, true],
["remove", ["codex"], true, true],
]);
diff --git a/apps/cua-spaces-macos/README.md b/apps/cua-spaces-macos/README.md
index d24ca18701..47a5837f8c 100644
--- a/apps/cua-spaces-macos/README.md
+++ b/apps/cua-spaces-macos/README.md
@@ -11,7 +11,7 @@ render and do platform glue.
| Main window | Sidebar with Spaces (one section per location; a dragged window drops on a row) and the Keyvault (All, Waiting, Access, Recent, one row per site) with the global Keyvault switch; Space detail with the live desktop, per-window streams, picture in picture, agent runs and the Teleport drop well |
| New Space | Step-by-step sheet: System, Resources, Options, Summary; Connect by address |
| Keyvault | Sidebar and list: categories, a site's accounts with their unattended switches, approval sheets |
-| Onboarding | The shared web onboarding (`/onboarding` in `apps/cua-spaces-web`), in the New UI window, whether or not the New UI setting is on; the app draws none of its own. The page asks and finishes it through `onboarding.get` and `onboarding.complete` (the state is `onboarding.json`); a Space it creates posts a "<Space> is ready" notification (`notifyWhenReady`) that opens the Space. With the New UI off, the window gives way to the native one when the first run ends |
+| Onboarding | The shared web onboarding (`/onboarding` in `apps/cua-spaces-web`), in the New UI window, whether or not the New UI setting is on; the app draws none of its own. The page asks and finishes it through `onboarding.get` and `onboarding.complete` (the state is `onboarding.json`); a Space it creates posts a "<Space> is ready" notification (`notifyWhenReady`) that opens the Space. With the New UI off, the window gives way to the native one when the first run ends. A launch (or a window that opens again) while it is not done opens `/onboarding?due=1`: the page goes to Spaces instead when the person chose "Skip for now" (kept in the page's storage), so the welcome does not come back at every launch; Settings → Welcome and the sidebar's "Finish setting up" open it without `due` and always show it |
| Devices | Settings → Devices: this Mac's enrollment (enrolled until, grace ends, needs enrollment), the account's devices with Rename and Revoke, Recent Access; the Enroll sheet (sign in again, or a one-time code approved from an enrolled device), the approval sheet for a device asking to join (a notification too; Approve asks for Touch ID or the login password), and a banner in the main window when this Mac needs enrolling |
| Menu bar | The Cua mark (template); status line, Open, New Space, Settings, Quit |
| Launch at login | Settings → General: `SMAppService.mainApp`, showing what macOS reports (on, off, waiting for approval with a button to Login Items, not found); the first run's Done page (the web onboarding's) ticks it. A login launch opens without the main window, and the app's daemon (host Spaces, persistent agents, Cua Volume) starts with it |
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/CuaSpacesMacApp.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/CuaSpacesMacApp.swift
index 410ffa956e..66b486603b 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/CuaSpacesMacApp.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/CuaSpacesMacApp.swift
@@ -417,8 +417,8 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
// launch opens (the main window is suppressed), the first run at
// `/onboarding`; not when opened at login.
if CuaSpacesMacApp.opensWebUIAtLaunch(model), !Self.launchedAtLogin {
- if !model.onboarding.completed {
- WebUIWindowController.show(model: model, at: .onboarding)
+ if let route = MainWindowSwitch.firstRunRoute(onboarded: model.onboarding.completed) {
+ WebUIWindowController.show(model: model, at: route)
} else if DevHooks.value("CUA_SPACES_START_VIEW") == nil {
WebUIWindowController.show(model: model)
}
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/MainUIRoute.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/MainUIRoute.swift
index 1b21cfdd0c..6e411eda9d 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/MainUIRoute.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/MainUIRoute.swift
@@ -25,9 +25,16 @@ public enum MainUIRoute: Equatable, Sendable {
/// A page path as given (`/machines?join=<CODE>` from a `cua://add` link).
case path(String)
- /// The first run: the shared web onboarding.
+ /// The first run, asked for by a person (Settings, Welcome): the shared
+ /// web onboarding, always shown.
static let onboarding = MainUIRoute.path("/onboarding")
+ /// The first run, opened because it is not done (a launch, or the window
+ /// opening again): the same page, which goes to Spaces instead when the
+ /// person chose "Skip for now", so the welcome does not come back at every
+ /// launch. The page keeps that choice, `due` asks it to honour it.
+ static let firstRunDue = MainUIRoute.path("/onboarding?due=1")
+
/// The page's path, query included.
var webPath: String {
switch self {
@@ -130,6 +137,13 @@ enum MainWindowSwitch {
opensFirstRun(ready: model.startup.isReady, onboarded: model.onboarding.completed)
}
+ /// Where a window opens while the first run may be due: its page until it
+ /// is done (`.firstRunDue`, which keeps a "Skip for now"), else nil, the
+ /// app as it was. The launch and the native window's replacement both ask.
+ static func firstRunRoute(onboarded: Bool) -> MainUIRoute? {
+ onboarded ? nil : .firstRunDue
+ }
+
/// The native window is up while the first run is due (and the launch is
/// ready): the web onboarding opens in its frame and it closes.
static func firstRunAppeared(_ window: NSWindow?, model: AppModel, web: ((NSRect?) -> Void)? = nil) {
@@ -183,8 +197,8 @@ enum MainWindowSwitch {
private static func show(_ model: AppModel, frame: NSRect?) {
// The first run opens on its page; the rest is the app as it was.
- if !model.onboarding.completed {
- WebUIWindowController.show(model: model, at: .onboarding, frame: frame)
+ if let route = firstRunRoute(onboarded: model.onboarding.completed) {
+ WebUIWindowController.show(model: model, at: route, frame: frame)
} else {
WebUIWindowController.show(model: model, frame: frame)
}
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/FirstRunTests.swift b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/FirstRunTests.swift
index f0dc403a16..f1b52630fa 100644
--- a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/FirstRunTests.swift
+++ b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/FirstRunTests.swift
@@ -46,6 +46,18 @@ struct FirstRunTests {
#expect(MainUIRoute.onboarding.webPath == "/onboarding")
}
+ /// A launch (or a window that opens again) while the first run is not
+ /// done asks for it as due, so the page can keep a "Skip for now": the
+ /// welcome came back at every launch, in Cua Spaces Local as in the
+ /// released app, because the app opened `/onboarding` itself. A person
+ /// asking for it (Settings, Welcome) still gets the page unconditionally.
+ @Test func aWindowOpeningWhileTheFirstRunIsDueLetsThePageHonourSkipForNow() {
+ #expect(MainUIRoute.firstRunDue.webPath == "/onboarding?due=1")
+ #expect(MainWindowSwitch.firstRunRoute(onboarded: false) == .firstRunDue)
+ #expect(MainWindowSwitch.firstRunRoute(onboarded: true) == nil, "done: the app as it was")
+ #expect(MainUIRoute.onboarding.webPath == "/onboarding", "Show again has no due: it always shows")
+ }
+
/// A window that is never shown (the replacement only reads its frame
/// and closes it).
func hiddenWindow() -> NSWindow {
diff --git a/apps/cua-spaces-web/src/__tests__/onboarding-skip-route.test.ts b/apps/cua-spaces-web/src/__tests__/onboarding-skip-route.test.ts
new file mode 100644
index 0000000000..c70f9fd81e
--- /dev/null
+++ b/apps/cua-spaces-web/src/__tests__/onboarding-skip-route.test.ts
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+// "Skip for now" keeps the first run away: the Mac app opens `/onboarding?due=1`
+// while the first run is not done (at launch, when its window opens again), and
+// the page goes to Spaces if the person skipped it. Without `due` (the
+// sidebar's "Finish setting up", Settings, the command palette) it always
+// shows. The welcome used to come back at every launch, in Cua Spaces Local as
+// in the released app, because the app opened `/onboarding` itself.
+
+import { createMemoryHistory, createRouter } from "@tanstack/react-router";
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { resetSavedOnboardingCache, writeSavedOnboarding } from "@/bridge/onboarding";
+import { routeTree } from "../routeTree.gen";
+
+/** A launch: the saved choice is read from storage again, as a new process does. */
+async function landsAt(path: string): Promise<string> {
+ resetSavedOnboardingCache();
+ const router = createRouter({ routeTree, history: createMemoryHistory({ initialEntries: [path] }) });
+ await router.load();
+ return router.state.location.pathname;
+}
+
+beforeEach(() => {
+ localStorage.clear();
+ resetSavedOnboardingCache();
+});
+
+describe("the first run after Skip for now", () => {
+ it("opens on a launch while it is not done and was not skipped", async () => {
+ expect(await landsAt("/onboarding?due=1")).toBe("/onboarding");
+ });
+
+ it("stays away on a launch after Skip for now, and stays away at the next one", async () => {
+ writeSavedOnboarding({ state: null, skipped: true });
+ expect(await landsAt("/onboarding?due=1")).toBe("/spaces");
+ expect(await landsAt("/onboarding?due=1")).toBe("/spaces");
+ });
+
+ it("still shows when a person asks for it, skipped or not", async () => {
+ writeSavedOnboarding({ state: null, skipped: true });
+ expect(await landsAt("/onboarding")).toBe("/onboarding");
+ expect(await landsAt("/onboarding?due=0")).toBe("/onboarding");
+ });
+});
diff --git a/apps/cua-spaces-web/src/routes/onboarding/index.tsx b/apps/cua-spaces-web/src/routes/onboarding/index.tsx
index 1f53e58fd3..4e49bfffe0 100644
--- a/apps/cua-spaces-web/src/routes/onboarding/index.tsx
+++ b/apps/cua-spaces-web/src/routes/onboarding/index.tsx
@@ -1,11 +1,12 @@
// SPDX-License-Identifier: FSL-1.1-MIT
// Copyright (c) 2026 Cua AI, Inc.
-import { createFileRoute, useNavigate } from "@tanstack/react-router";
+import { createFileRoute, redirect, useNavigate } from "@tanstack/react-router";
import { CheckIcon, CopyIcon } from "lucide-react";
import { useEffect, useState, type ReactNode } from "react";
import { useAgentKeys, useFirstRun, type FirstRunArt, type FirstRunCredential, type FirstRunExtraView, type FirstRunHook, type FirstRunRow, type FirstRunView } from "@/bridge";
+import { readSavedOnboarding } from "@/bridge/onboarding";
import { KeySheet } from "@/components/agents/key-sheet";
import { CuaLogo } from "@/components/cua-logo";
import { OsIcon } from "@/components/os-icon";
@@ -16,7 +17,19 @@ import { toast } from "@/components/ui/toast";
import { RuntimeFixRow } from "@/components/new-space/runtime-fix";
import { cn } from "@/lib/utils";
-export const Route = createFileRoute("/onboarding/")({ component: OnboardingPage });
+export const Route = createFileRoute("/onboarding/")({
+ // `?due=1` is a host opening the first run because it is not done (the Mac
+ // app at launch, or when its window opens again). The page keeps to what
+ // the person chose: after "Skip for now" it goes to Spaces instead, as the
+ // root route does for a host that opens the app at `/`. Every other way in
+ // (the sidebar's "Finish setting up", Settings, the command palette) has
+ // no `due` and always shows the first run.
+ validateSearch: (s: Record<string, unknown>): { due?: true } => (s.due === 1 || s.due === "1" || s.due === true ? { due: true as const } : {}),
+ beforeLoad: ({ search }) => {
+ if (search.due && readSavedOnboarding().skipped) throw redirect({ to: "/spaces" });
+ },
+ component: OnboardingPage,
+});
/**
* The first run, the same on macOS, Windows and Linux: Welcome, Pick your
diff --git a/libs/cua/crates/cua-home/tests/app_agent_setup_names_test.rs b/libs/cua/crates/cua-home/tests/app_agent_setup_names_test.rs
new file mode 100644
index 0000000000..aaa0013cfa
--- /dev/null
+++ b/libs/cua/crates/cua-home/tests/app_agent_setup_names_test.rs
@@ -0,0 +1,104 @@
+//! The apps register Cua's MCP server in a coding agent (Claude Code, Codex,
+//! ...) without a name of their own: the SDK names it for the app's channel
+//! (`CuaChannel::mcp_server_name`, `cua` or `cua-local`) and installs the
+//! channel's skill copies (CUA-1776). An app that wrote `cua` itself would
+//! have Cua Spaces Local replace the released app's entry in the user's
+//! `~/.claude.json` on "Continue".
+//!
+//! The SDK's record defaults its name to `cua` (`AgentMcpServer`), which a
+//! caller that leaves it out gets, so every caller says `name: ""` out loud.
+//! The behaviour behind it is tested where it lives: an empty name is the
+//! channel's (`cua-sdk`'s `agent_setup` tests), and a Local setup leaves
+//! Stable's entry alone (`cua-agent-setup`'s `local_channel` test).
+//!
+//! The Swift and Electron sources are read straight from the repository; the
+//! check is skipped where the apps are not there (the crate published on
+//! crates.io).
+
+use cua_home::channel::CuaChannel;
+use std::path::{Path, PathBuf};
+
+fn repo(rel: &str) -> PathBuf {
+ PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+ .join("../../../..")
+ .join(rel)
+}
+
+fn swift_files(dir: &Path, out: &mut Vec<PathBuf>) {
+ let Ok(entries) = std::fs::read_dir(dir) else {
+ return;
+ };
+ for e in entries.flatten() {
+ let p = e.path();
+ if p.is_dir() {
+ swift_files(&p, out);
+ } else if p.extension().is_some_and(|x| x == "swift") {
+ out.push(p);
+ }
+ }
+}
+
+/// Every `AgentMcpServer(` the Swift app builds, with the text up to its
+/// closing parenthesis.
+fn swift_servers() -> Option<Vec<(PathBuf, String)>> {
+ let root = repo("apps/cua-spaces-macos/Sources");
+ if !root.is_dir() {
+ return None;
+ }
+ let mut files = Vec::new();
+ swift_files(&root, &mut files);
+ let mut found = Vec::new();
+ for f in files {
+ let text = std::fs::read_to_string(&f).unwrap();
+ for (at, _) in text.match_indices("AgentMcpServer(") {
+ let call = &text[at..];
+ let end = call.find(')').map_or(call.len(), |i| i + 1);
+ found.push((f.clone(), call[..end].to_string()));
+ }
+ }
+ Some(found)
+}
+
+#[test]
+fn the_swift_app_leaves_the_mcp_server_name_to_the_channel() {
+ let Some(servers) = swift_servers() else {
+ eprintln!("SKIP: no apps/cua-spaces-macos in this checkout");
+ return;
+ };
+ // The app builds one server (`LiveAgentSetup`); a second one must say the same.
+ assert!(
+ !servers.is_empty(),
+ "no AgentMcpServer in the Swift app: did LiveAgentSetup move? Update this test"
+ );
+ for (file, call) in &servers {
+ assert!(
+ call.contains("name: \"\""),
+ "{} builds `{call}`: pass `name: \"\"` so the SDK names the server for the channel \
+ (`cua` or `cua-local`); the SDK's default, `cua`, is Stable's",
+ file.display()
+ );
+ }
+}
+
+#[test]
+fn the_electron_app_leaves_the_mcp_server_name_to_the_channel() {
+ let Ok(ts) = std::fs::read_to_string(repo("apps/cua-spaces-desktop/src/model/agents.ts"))
+ else {
+ eprintln!("SKIP: no apps/cua-spaces-desktop in this checkout");
+ return;
+ };
+ assert!(
+ ts.contains("{ name: \"\", command: cuaBinary,"),
+ "LiveAgentSetup no longer builds its server with an empty name: the SDK names it for the \
+ channel (`cua` or `cua-local`)"
+ );
+ for stable in [
+ format!("name: \"{}\"", CuaChannel::Stable.mcp_server_name()),
+ format!("name: \"{}\"", CuaChannel::Local.mcp_server_name()),
+ ] {
+ assert!(
+ !ts.contains(&stable),
+ "agents.ts names the MCP server itself ({stable}); the channel does that"
+ );
+ }
+}